{"openapi":"3.1.0","info":{"title":"SocialCrawl API","version":"1.0.0","description":"Unified social media data API — one API key, one consistent response format, 44 platforms, 357 endpoints. Power AI agents with clean social data.","contact":{"name":"SocialCrawl","url":"https://www.socialcrawl.dev","email":"support@socialcrawl.dev"}},"servers":[{"url":"https://www.socialcrawl.dev/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"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."}},"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_KEY_PAYLOAD_MISMATCH","PAYLOAD_TOO_LARGE"],"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."},"details":{"type":["object","null"],"additionalProperties":true,"description":"Optional structured context (e.g. the comment-lookup not-found taxonomy). Omitted on ordinary errors."}},"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, or null when the balance could not be read (e.g. auth failed before lookup)."},"request_id":{"type":"string","description":"Unique request identifier — matches the X-Request-Id header. Quote it in support requests."}},"required":["success","error","credits_used","credits_remaining","request_id"]}}},"tags":[{"name":"ai-search","description":"Ai-search endpoints"},{"name":"amazon","description":"Amazon endpoints"},{"name":"app_store","description":"App_store endpoints"},{"name":"bluesky","description":"Bluesky endpoints"},{"name":"content_analysis","description":"Content_analysis endpoints"},{"name":"facebook","description":"Facebook endpoints"},{"name":"facebook-ads","description":"Facebook-ads endpoints"},{"name":"geo","description":"Geo endpoints"},{"name":"github","description":"Github endpoints"},{"name":"google","description":"Google endpoints"},{"name":"google-ads","description":"Google-ads endpoints"},{"name":"google_finance","description":"Google_finance endpoints"},{"name":"google_news","description":"Google_news endpoints"},{"name":"google_play","description":"Google_play endpoints"},{"name":"google_shopping","description":"Google_shopping endpoints"},{"name":"google_trends","description":"Google_trends endpoints"},{"name":"hackernews","description":"Hackernews endpoints"},{"name":"instagram","description":"Instagram endpoints"},{"name":"kick","description":"Kick endpoints"},{"name":"komi","description":"Komi endpoints"},{"name":"kwai","description":"Kwai endpoints"},{"name":"linkbio","description":"Linkbio endpoints"},{"name":"linkedin","description":"Linkedin endpoints"},{"name":"linkedin-ads","description":"Linkedin-ads endpoints"},{"name":"linkme","description":"Linkme endpoints"},{"name":"linktree","description":"Linktree endpoints"},{"name":"meta","description":"Account metadata — balance, usage, no credit deduction"},{"name":"naver","description":"Naver endpoints"},{"name":"perplexity","description":"Perplexity endpoints"},{"name":"pillar","description":"Pillar endpoints"},{"name":"pinterest","description":"Pinterest endpoints"},{"name":"polymarket","description":"Polymarket endpoints"},{"name":"prism","description":"Prism endpoints"},{"name":"reddit","description":"Reddit endpoints"},{"name":"rumble","description":"Rumble endpoints"},{"name":"search","description":"Search endpoints"},{"name":"snapchat","description":"Snapchat endpoints"},{"name":"spotify","description":"Spotify endpoints"},{"name":"tavily","description":"Tavily endpoints"},{"name":"threads","description":"Threads endpoints"},{"name":"tiktok","description":"Tiktok endpoints"},{"name":"tiktokshop","description":"Tiktokshop endpoints"},{"name":"tripadvisor","description":"Tripadvisor endpoints"},{"name":"trustpilot","description":"Trustpilot endpoints"},{"name":"truthsocial","description":"Truthsocial endpoints"},{"name":"twitch","description":"Twitch endpoints"},{"name":"twitter","description":"Twitter endpoints"},{"name":"utility","description":"Utility endpoints"},{"name":"web","description":"Web endpoints"},{"name":"youtube","description":"Youtube endpoints"}],"paths":{"/web/scrape":{"get":{"summary":"Scrape a web page","description":"Fetches a public web page and returns clean content, metadata, and optional media in the unified WebPage schema.","tags":["web"],"operationId":"get_web_scrape","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Public URL to fetch.","schema":{"type":"string"},"example":"https://example.com"},{"name":"formats","in":"query","required":false,"description":"Comma-separated output formats such as markdown,screenshot.","schema":{"type":"string"},"example":"markdown"},{"name":"only_main_content","in":"query","required":false,"description":"only_main_content","schema":{"type":"boolean"}},{"name":"wait_for","in":"query","required":false,"description":"wait_for","schema":{"type":"integer"}},{"name":"mobile","in":"query","required":false,"description":"mobile","schema":{"type":"boolean"}},{"name":"timeout","in":"query","required":false,"description":"timeout","schema":{"type":"integer"}},{"name":"max_age","in":"query","required":false,"description":"max_age","schema":{"type":"integer"}},{"name":"location_country","in":"query","required":false,"description":"location_country","schema":{"type":"string"}},{"name":"screenshot_full_page","in":"query","required":false,"description":"screenshot_full_page","schema":{"type":"boolean"}},{"name":"include_tags","in":"query","required":false,"description":"include_tags","schema":{"type":"string"}},{"name":"exclude_tags","in":"query","required":false,"description":"exclude_tags","schema":{"type":"string"}},{"name":"proxy","in":"query","required":false,"description":"Proxy tier: basic, auto, or enhanced.","schema":{"type":"string","enum":["basic","auto","enhanced"]}},{"name":"pdf_parse","in":"query","required":false,"description":"pdf_parse","schema":{"type":"boolean"}},{"name":"block_ads","in":"query","required":false,"description":"block_ads","schema":{"type":"boolean"}},{"name":"remove_base64_images","in":"query","required":false,"description":"remove_base64_images","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/search":{"get":{"summary":"Search the web","description":"Searches web, news, and image sources and returns a single normalized list of web page results.","tags":["web"],"operationId":"get_web_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":2,"parameters":[{"name":"query","in":"query","required":true,"description":"Search query.","schema":{"type":"string"},"example":"social media data api"},{"name":"sources","in":"query","required":false,"description":"Comma-separated sources: web,news,images.","schema":{"type":"string"}},{"name":"categories","in":"query","required":false,"description":"categories","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per source, from 1 to 100.","schema":{"type":"integer"},"example":10},{"name":"country","in":"query","required":false,"description":"country","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"location","schema":{"type":"string"}},{"name":"time_range","in":"query","required":false,"description":"time_range","schema":{"type":"string"}},{"name":"sort_by_date","in":"query","required":false,"description":"sort_by_date","schema":{"type":"boolean"}},{"name":"include_domains","in":"query","required":false,"description":"include_domains","schema":{"type":"string"}},{"name":"exclude_domains","in":"query","required":false,"description":"exclude_domains","schema":{"type":"string"}},{"name":"include_content","in":"query","required":false,"description":"include_content","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical web page wrappers ({ page })","items":{"type":"object","description":"Canonical web page wrapper","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/map":{"get":{"summary":"Map URLs on a site","description":"Discovers URLs for a public site and returns them as a normalized WebPageList.","tags":["web"],"operationId":"get_web_map","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Site URL to map.","schema":{"type":"string"},"example":"https://example.com"},{"name":"search","in":"query","required":false,"description":"Optional path or keyword filter.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum URLs to return, up to 5000.","schema":{"type":"integer"},"example":100},{"name":"sitemap","in":"query","required":false,"description":"sitemap","schema":{"type":"string","enum":["include","skip","only"]}},{"name":"include_subdomains","in":"query","required":false,"description":"include_subdomains","schema":{"type":"boolean"}},{"name":"ignore_query_parameters","in":"query","required":false,"description":"ignore_query_parameters","schema":{"type":"boolean"}},{"name":"fresh","in":"query","required":false,"description":"fresh","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical web page wrappers ({ page })","items":{"type":"object","description":"Canonical web page wrapper","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/extract":{"get":{"summary":"Extract structured data from a web page","description":"Fetches one web page and returns structured extraction output under the WebPage extraction field.","tags":["web"],"operationId":"get_web_extract","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["schema","prompt"]],"parameters":[{"name":"url","in":"query","required":true,"description":"Public URL to extract from.","schema":{"type":"string"},"example":"https://example.com/pricing"},{"name":"schema","in":"query","required":false,"description":"JSON object schema describing the data to return. (one of: schema, prompt — at least one required)","schema":{"type":"string"}},{"name":"prompt","in":"query","required":false,"description":"Plain-language extraction instruction. (one of: schema, prompt — at least one required)","schema":{"type":"string"},"example":"Extract plan names and prices."},{"name":"only_main_content","in":"query","required":false,"description":"only_main_content","schema":{"type":"boolean"}},{"name":"timeout","in":"query","required":false,"description":"timeout","schema":{"type":"integer"}},{"name":"max_age","in":"query","required":false,"description":"max_age","schema":{"type":"integer"}},{"name":"proxy","in":"query","required":false,"description":"proxy","schema":{"type":"string","enum":["basic","auto","enhanced"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/crawl":{"post":{"summary":"Start an async web crawl","description":"Starts an async crawl job and returns a SocialCrawl job id (job_...). Poll or cancel it via GET/DELETE /v1/web/jobs/{job_id}, or track it with a webhook.","tags":["web"],"operationId":"post_web_crawl","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/crawl","data":{"job_id":"job_9f3k2n8d1","kind":"crawl","resource":"crawl","status":"queued","progress":null,"invalid_urls":null,"result_ref":null,"result":null,"error":null,"credits_hold":10,"credits_charged":0,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:00.000Z","expires_at":"2026-07-16T09:30:00.000Z"},"credits_used":10,"credits_remaining":990,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for web/crawl. Required: url.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"limit":{"type":"integer"},"max_depth":{"type":"integer"},"allow_backward_links":{"type":"boolean"},"allow_external_links":{"type":"boolean"},"include_paths":{"type":"string"},"exclude_paths":{"type":"string"},"webhook_url":{"type":"string"},"formats":{"type":"string"}},"required":["url"]}}}}}},"/web/batch-scrape":{"post":{"summary":"Start an async batch scrape","description":"Starts an async batch scrape job for multiple URLs and returns a SocialCrawl job id (job_...). Poll or cancel it via GET/DELETE /v1/web/jobs/{job_id}.","tags":["web"],"operationId":"post_web_batch_scrape","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/batch-scrape","data":{"job_id":"job_7t2m4c9x5","kind":"batch_scrape","resource":"batch-scrape","status":"queued","progress":null,"invalid_urls":null,"result_ref":null,"result":null,"error":null,"credits_hold":2,"credits_charged":0,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:00.000Z","expires_at":"2026-07-16T09:30:00.000Z"},"credits_used":2,"credits_remaining":998,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for web/batch-scrape. Required: urls.","content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string"}},"ignore_invalid_urls":{"type":"boolean"},"formats":{"type":"string"},"only_main_content":{"type":"boolean"},"proxy":{"type":"string","enum":["basic","auto","enhanced"]},"webhook_url":{"type":"string"}},"required":["urls"]}}}}}},"/web/jobs":{"get":{"summary":"List async web jobs","description":"Lists async crawl, batch scrape, and agent jobs for the API key.","tags":["web"],"operationId":"get_web_jobs","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, capped at 100.","schema":{"type":"integer"},"example":20},{"name":"cursor","in":"query","required":false,"description":"Previous response cursor.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical web page wrappers ({ page })","items":{"type":"object","description":"Canonical web page wrapper","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/jobs","data":{"items":[{"job_id":"job_9f3k2n8d1","kind":"crawl","resource":"crawl","status":"completed","progress":{"completed":10,"total":10},"invalid_urls":null,"result_ref":"web-jobs/job_9f3k2n8d1.json","result":null,"error":null,"credits_hold":10,"credits_charged":10,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:34:12.000Z","expires_at":"2026-07-16T09:30:00.000Z"}],"has_more":false,"next_cursor":null},"credits_used":0,"credits_remaining":990,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/jobs/{job_id}":{"get":{"summary":"Get an async web job","description":"Returns the current status, billing settlement, progress, and any available result metadata for one async web job — crawl, batch scrape, or agent. Append /errors to the same path to list per-page failures and robots-blocked URLs (crawl and batch scrape jobs).","tags":["web"],"operationId":"get_web_jobs_job_id","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"job_id","in":"path","required":true,"description":"Job id (job_...) returned by POST /v1/web/crawl, POST /v1/web/batch-scrape, or POST /v1/web/agent as data.job_id.","schema":{"type":"string"},"example":"job_9f3k2n8d1"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/jobs/job_9f3k2n8d1","data":{"job_id":"job_9f3k2n8d1","kind":"crawl","resource":"crawl","status":"completed","progress":{"completed":10,"total":10},"invalid_urls":null,"result_ref":"web-jobs/job_9f3k2n8d1.json","result":null,"error":null,"credits_hold":10,"credits_charged":10,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:34:12.000Z","expires_at":"2026-07-16T09:30:00.000Z"},"credits_used":0,"credits_remaining":990,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}},"delete":{"summary":"Cancel an async web job","description":"Cancels one async web job of any kind (crawl, batch scrape, or agent), closes the upstream work when possible, and refunds any unsettled held credits.","tags":["web"],"operationId":"delete_web_jobs_job_id","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"job_id","in":"path","required":true,"description":"Job id (job_...) returned by POST /v1/web/crawl, POST /v1/web/batch-scrape, or POST /v1/web/agent as data.job_id.","schema":{"type":"string"},"example":"job_9f3k2n8d1"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/jobs/job_9f3k2n8d1","data":{"job_id":"job_9f3k2n8d1","kind":"crawl","resource":"crawl","status":"cancelled","progress":{"completed":3,"total":10},"invalid_urls":null,"result_ref":null,"result":null,"error":null,"credits_hold":10,"credits_charged":0,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:31:40.000Z","expires_at":"2026-07-16T09:30:00.000Z"},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/agent":{"post":{"summary":"Start an async web agent job","description":"Runs a model-neutral browser agent task and returns a SocialCrawl async job id (job_...). Poll it via GET /v1/web/jobs/{job_id}.","tags":["web"],"operationId":"post_web_agent","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":25,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/agent","data":{"job_id":"job_2q8w6r4v3","kind":"agent","resource":"agent","status":"queued","progress":null,"invalid_urls":null,"result_ref":null,"result":null,"error":null,"credits_hold":25,"credits_charged":0,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:00.000Z","expires_at":"2026-07-16T09:30:00.000Z"},"credits_used":25,"credits_remaining":975,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for web/agent. Required: url, prompt.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"prompt":{"type":"string"},"model":{"type":"string","enum":["spark-1-mini","spark-1-pro"]}},"required":["url","prompt"]}}}}}},"/web/monitors":{"post":{"summary":"Create a web monitor","description":"Creates an upstream-backed monitor. Checks are billed when they run, not at creation.","tags":["web"],"operationId":"post_web_monitors","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/monitors","data":{"monitor_id":"wm_5d1p8s3k7","url":"https://example.com","mode":"scrape","status":"active","params":{"url":"https://example.com","name":"Example monitor"},"cadence_minutes":15,"credits_booked":1,"consecutive_failures":0,"last_check_at":null,"next_check_at":"2026-07-09T09:45:00.000Z","created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:00.000Z"},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for web/monitors. Required: url.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string","enum":["scrape","search"]},"cadence_minutes":{"type":"integer"},"schedule_text":{"type":"string"},"schedule_cron":{"type":"string"},"timezone":{"type":"string"},"webhook_url":{"type":"string"},"query":{"type":"string"},"goal":{"type":"string"},"retention_days":{"type":"integer"},"judge_enabled":{"type":"boolean"}},"required":["url"]}}}}},"get":{"summary":"List web monitors","description":"Lists web monitors created by the current API key.","tags":["web"],"operationId":"get_web_monitors","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"cursor","in":"query","required":false,"description":"Pagination cursor.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer"},"example":20},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical web page wrappers ({ page })","items":{"type":"object","description":"Canonical web page wrapper","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/monitors","data":{"items":[{"monitor_id":"wm_5d1p8s3k7","url":"https://example.com","mode":"scrape","status":"active","params":{"url":"https://example.com"},"cadence_minutes":15,"credits_booked":1,"consecutive_failures":0,"last_check_at":"2026-07-09T09:15:00.000Z","next_check_at":"2026-07-09T09:45:00.000Z","created_at":"2026-07-08T18:00:00.000Z","updated_at":"2026-07-09T09:15:00.000Z"}],"has_more":false,"next_cursor":null},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/monitors/{monitor_id}":{"get":{"summary":"Get a web monitor","description":"Returns configuration, cadence, status, and billing metadata for one web monitor.","tags":["web"],"operationId":"get_web_monitors_monitor_id","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"monitor_id","in":"path","required":true,"description":"Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id.","schema":{"type":"string"},"example":"wm_5d1p8s3k7"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/monitors/wm_5d1p8s3k7","data":{"monitor_id":"wm_5d1p8s3k7","url":"https://example.com","mode":"scrape","status":"active","params":{"url":"https://example.com"},"cadence_minutes":15,"credits_booked":1,"consecutive_failures":0,"last_check_at":"2026-07-09T09:15:00.000Z","next_check_at":"2026-07-09T09:45:00.000Z","created_at":"2026-07-08T18:00:00.000Z","updated_at":"2026-07-09T09:15:00.000Z"},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}},"patch":{"summary":"Update a web monitor","description":"Updates one web monitor's status or cadence while preserving its check history and billing metadata.","tags":["web"],"operationId":"patch_web_monitors_monitor_id","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"monitor_id","in":"path","required":true,"description":"Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id.","schema":{"type":"string"},"example":"wm_5d1p8s3k7"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/monitors/wm_5d1p8s3k7","data":{"monitor_id":"wm_5d1p8s3k7","url":"https://example.com","mode":"scrape","status":"paused","params":{"url":"https://example.com"},"cadence_minutes":15,"credits_booked":1,"consecutive_failures":0,"last_check_at":"2026-07-09T09:15:00.000Z","next_check_at":"2026-07-09T09:45:00.000Z","created_at":"2026-07-08T18:00:00.000Z","updated_at":"2026-07-09T09:32:00.000Z"},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":false,"description":"JSON body for web/monitors/{monitor_id}. Required: monitor_id.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]},"cadence_minutes":{"type":"integer"},"schedule_text":{"type":"string"},"schedule_cron":{"type":"string"},"timezone":{"type":"string"}},"required":[]}}}}},"delete":{"summary":"Delete a web monitor","description":"Deletes one web monitor, stops future scheduled checks, and keeps historical check records available.","tags":["web"],"operationId":"delete_web_monitors_monitor_id","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"monitor_id","in":"path","required":true,"description":"Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id.","schema":{"type":"string"},"example":"wm_5d1p8s3k7"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/monitors/wm_5d1p8s3k7","data":{"monitor_id":"wm_5d1p8s3k7","url":"https://example.com","mode":"scrape","status":"deleted","params":{"url":"https://example.com"},"cadence_minutes":15,"credits_booked":1,"consecutive_failures":0,"last_check_at":"2026-07-09T09:15:00.000Z","next_check_at":"2026-07-09T09:45:00.000Z","created_at":"2026-07-08T18:00:00.000Z","updated_at":"2026-07-09T09:35:00.000Z"},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/monitors/{monitor_id}/checks":{"get":{"summary":"List web monitor checks","description":"Lists checks recorded for one monitor.","tags":["web"],"operationId":"get_web_monitors_monitor_id_checks","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"monitor_id","in":"path","required":true,"description":"Monitor id (wm_...) returned by POST /v1/web/monitors as data.monitor_id.","schema":{"type":"string"},"example":"wm_5d1p8s3k7"},{"name":"limit","in":"query","required":false,"description":"limit","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical web page wrappers ({ page })","items":{"type":"object","description":"Canonical web page wrapper","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/monitors/wm_5d1p8s3k7/checks","data":{"items":[{"check_id":"wc_8n4b2j6h9","status":"completed","credits_charged":1,"result":null,"error":null,"checked_at":"2026-07-09T09:15:00.000Z","created_at":"2026-07-09T09:15:00.000Z"}]},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/sessions":{"post":{"summary":"Create an interactive web session","description":"Creates a short-lived browser session for follow-up interactions.","tags":["web"],"operationId":"post_web_sessions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/sessions","data":{"session_id":"ws_3g7x1v5m2","kind":"browser","status":"active","ttl_seconds":60,"credits_hold":5,"credits_billed":0,"expires_at":"2026-07-09T09:31:00.000Z","closed_at":null,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:00.000Z"},"credits_used":5,"credits_remaining":995,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for web/sessions. Required: url.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"ttl_seconds":{"type":"integer"},"activity_ttl_seconds":{"type":"integer"},"stream_web_view":{"type":"boolean"}},"required":["url"]}}}}},"get":{"summary":"List interactive web sessions","description":"Lists sessions created by the current API key.","tags":["web"],"operationId":"get_web_sessions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size.","schema":{"type":"integer"},"example":20},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical web page wrappers ({ page })","items":{"type":"object","description":"Canonical web page wrapper","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/sessions","data":{"items":[{"session_id":"ws_3g7x1v5m2","kind":"browser","status":"active","ttl_seconds":60,"credits_hold":5,"credits_billed":0,"expires_at":"2026-07-09T09:31:00.000Z","closed_at":null,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:00.000Z"}],"has_more":false,"next_cursor":null},"credits_used":0,"credits_remaining":995,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/sessions/{session_id}":{"get":{"summary":"Get an interactive web session","description":"Returns status, expiry, billing hold, and settlement metadata for one interactive web session.","tags":["web"],"operationId":"get_web_sessions_session_id","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"session_id","in":"path","required":true,"description":"Session id (ws_...) returned by POST /v1/web/sessions as data.session_id.","schema":{"type":"string"},"example":"ws_3g7x1v5m2"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/sessions/ws_3g7x1v5m2","data":{"session_id":"ws_3g7x1v5m2","kind":"browser","status":"active","ttl_seconds":60,"credits_hold":5,"credits_billed":0,"expires_at":"2026-07-09T09:31:00.000Z","closed_at":null,"created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:00.000Z"},"credits_used":0,"credits_remaining":995,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}},"delete":{"summary":"Close an interactive web session","description":"Closes one interactive web session and settles any held credits that have not already been billed.","tags":["web"],"operationId":"delete_web_sessions_session_id","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"session_id","in":"path","required":true,"description":"Session id (ws_...) returned by POST /v1/web/sessions as data.session_id.","schema":{"type":"string"},"example":"ws_3g7x1v5m2"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/sessions/ws_3g7x1v5m2","data":{"session_id":"ws_3g7x1v5m2","kind":"browser","status":"closed","ttl_seconds":60,"credits_hold":5,"credits_billed":0,"expires_at":"2026-07-09T09:31:00.000Z","closed_at":"2026-07-09T09:30:40.000Z","created_at":"2026-07-09T09:30:00.000Z","updated_at":"2026-07-09T09:30:40.000Z"},"credits_used":0,"credits_remaining":1000,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/web/sessions/{session_id}/execute":{"post":{"summary":"Execute an interaction in a web session","description":"Runs code in an existing browser session and returns the execution result.","tags":["web"],"operationId":"post_web_sessions_session_id_execute","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":0,"parameters":[{"name":"session_id","in":"path","required":true,"description":"SocialCrawl session id.","schema":{"type":"string"},"example":"ws_3g7x1v5m2"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/sessions/ws_3g7x1v5m2/execute","data":{"success":true,"stdout":"Example Domain\n","stderr":"","result":null,"exitCode":0,"killed":false},"credits_used":0,"credits_remaining":995,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for web/sessions/{session_id}/execute. Required: session_id, code.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"language":{"type":"string","enum":["node","python","bash"]},"timeout":{"type":"integer"}},"required":["code"]}}}}}},"/web/parse":{"post":{"summary":"Parse an uploaded document","description":"Uploads a document through multipart/form-data and returns parsed web-style content.","tags":["web"],"operationId":"post_web_parse","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"page":{"type":"object","description":"Canonical web page object with identity, content, media, extraction, and fetch provenance fields.","properties":{"url":{"type":["string","null"],"description":"Requested URL."},"final_url":{"type":["string","null"],"description":"Final resolved URL after redirects."},"status_code":{"type":["number","null"],"description":"HTTP status code observed while fetching the page."},"scrape_id":{"type":["string","null"],"description":"Opaque scrape identifier for follow-up interactions."},"fetched_at":{"type":["string","null"],"description":"Fetch timestamp when reported."},"content":{"type":"object","description":"Extracted page content.","properties":{"markdown":{"type":["string","null"],"description":"Markdown body."},"html":{"type":["string","null"],"description":"HTML body."},"raw_html":{"type":["string","null"],"description":"Raw HTML body."},"summary":{"type":["string","null"],"description":"Generated summary."}}},"media":{"type":"object","description":"Short-lived media URLs returned for the page.","properties":{"screenshot_url":{"type":["string","null"],"description":"Screenshot URL when requested."},"audio_url":{"type":["string","null"],"description":"Audio URL."},"video_url":{"type":["string","null"],"description":"Video URL."}}},"extraction":{"type":["object","null"],"description":"Structured extraction result when requested."},"fetch":{"type":"object","description":"Vendor-neutral fetch provenance.","properties":{"cache_state":{"type":["string","null"],"description":"Upstream cache state when reported."},"cached_at":{"type":["string","null"],"description":"Upstream cache timestamp when reported."},"proxy_tier":{"type":["string","null"],"description":"Proxy tier used for the fetch."}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"web","endpoint":"/v1/web/parse","data":{"page":{"url":null,"final_url":null,"status_code":null,"scrape_id":"sc_6k9d3f8b4","fetched_at":"2026-07-09T09:30:02.000Z","title":"document.pdf","description":null,"source_type":null,"content":{"markdown":"# Quarterly report\n\nRevenue grew 12%...","html":null,"raw_html":null,"summary":null},"media":{"screenshot_url":null,"audio_url":null,"video_url":null},"extraction":null,"answer":null,"highlights":null,"change_tracking":null,"page_count":3,"total_page_count":3,"fetch":{"cache_state":null,"cached_at":null,"proxy_tier":null}}},"credits_used":1,"credits_remaining":999,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for web/parse. Required: file.","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string"},"filename":{"type":"string"},"mime_type":{"type":"string"},"url":{"type":"string"}},"required":["file"]}}}}}},"/tiktok/profile":{"get":{"summary":"Get TikTok user profile","description":"Returns public profile information for a TikTok user — follower count, following count, total likes, bio, avatar URL, and verification status. Pass either `handle` or `user_id`.","tags":["tiktok"],"operationId":"get_tiktok_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"TikTok username without the @ symbol. (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"charlidamelio"},{"name":"user_id","in":"query","required":false,"description":"TikTok numeric user ID. Use this for faster responses. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/profile/videos":{"get":{"summary":"List TikTok user videos","description":"Returns a paginated list of recent public videos posted by a TikTok user. Each video includes view count, like count, comment count, share count, caption, and thumbnail URL.","tags":["tiktok"],"operationId":"get_tiktok_profile_videos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"TikTok username without the @ symbol","schema":{"type":"string"},"example":"charlidamelio"},{"name":"user_id","in":"query","required":false,"description":"TikTok user id. Use this for faster responses.","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"What to sort by","schema":{"type":"string","enum":["latest","popular"]}},{"name":"max_cursor","in":"query","required":false,"description":"Cursor to get more videos. Get 'max_cursor' from previous response.","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"Region (Country) you want the proxy in. Defaults to US.","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/post":{"get":{"summary":"Get TikTok post details","description":"Returns detailed information about a specific TikTok video including view count, like count, comment count, share count, caption, music info, author details, and video metadata.","tags":["tiktok"],"operationId":"get_tiktok_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the TikTok video","schema":{"type":"string"},"example":"https://www.tiktok.com/@charlidamelio/video/7321485815660738859"},{"name":"region","in":"query","required":false,"description":"Region of the proxy. Sometimes you'll need to specify the region if you're not getting a response. Commonly for videos from the Phillipines, in which case you'd use 'PH'. Use 2 letter country codes like US, GB, FR, etc","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"download_media","in":"query","required":false,"description":"Set to true to also download the video/images and get back permanent, durable media URLs under `data.post.ext.download_media_urls` (`[{ post_id, cdn_url, type, cached }]`). Use these for archiving — the raw `media_urls` are short-lived signed CDN links that expire. Adds a few seconds of latency while the media is fetched.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/post/comments":{"get":{"summary":"List TikTok post comments","description":"Returns a list of comments on a specific TikTok video. Each comment includes the author username, comment text, like count, reply count, and creation timestamp.","tags":["tiktok"],"operationId":"get_tiktok_post_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the TikTok video to fetch comments for","schema":{"type":"string"},"example":"https://www.tiktok.com/@charlidamelio/video/7321485815660738859"},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more comments. Get 'cursor' from previous response.","schema":{"type":"integer"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/video/comment/replies":{"get":{"summary":"List TikTok comment replies","description":"Fetches replies to a specific TikTok comment by its ID. Returns an array of comment objects each with text, user info, and creation time. Paginate with the cursor from the previous response.","tags":["tiktok"],"operationId":"get_tiktok_video_comment_replies","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"comment_id","in":"query","required":true,"description":"TikTok comment ID. This is the cid from the comments endpoint.","schema":{"type":"string"},"example":"7623828115408274207"},{"name":"url","in":"query","required":true,"description":"TikTok video URL. This is the url from the comments endpoint.","schema":{"type":"string"},"example":"https://www.tiktok.com/@stoolpresidente/video/7623818255903329566"},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more replies. Get 'cursor' from previous response.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/comment":{"get":{"summary":"Look up one TikTok comment by URL or id","description":"Resolves a single TikTok comment to a live comment object (current like count, reply count, pinned flag, author, timestamp) without you paginating the comment section. Pass `comment_url` (a `.../@{handle}/video/{id}?comment_id={cid}` link, an `m.tiktok.com` share link, or a `vm.tiktok.com`/`.../t/` shortlink — resolved automatically) OR `post_url` + `comment_id`. For a reply, also pass `parent_comment_id` (a reply URL does not carry its parent). Instead of a comment id you can search the comment section: `author_username` (find a specific author's comments) or `text_contains` (exact snippet) return up to `max` matches. The response includes a `lookup.position_hint` — pass it back on a later lookup of the same comment to make the re-check nearly free. Flat 2 credits (6 with `deep_scan=true`, which widens the scan budget); a not-found returns 404 and is fully refunded.","tags":["tiktok"],"operationId":"get_tiktok_comment","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":2,"parameters":[{"name":"comment_url","in":"query","required":false,"description":"A TikTok comment URL: `https://www.tiktok.com/@{handle}/video/{videoId}?comment_id={cid}`, the `m.tiktok.com/v/{id}.html?...&share_comment_id={cid}` share form, or a `vm.tiktok.com/{code}` / `tiktok.com/t/{code}` shortlink. Mutually exclusive with `post_url`+`comment_id`.","schema":{"type":"string"},"example":"https://www.tiktok.com/@mrbeast/video/7654638524729216287?comment_id=7654640784985211670"},{"name":"post_url","in":"query","required":false,"description":"The post URL (`https://www.tiktok.com/@{handle}/video/{videoId}`). Combine with `comment_id`, or with `author_username`/`text_contains` for a search.","schema":{"type":"string"}},{"name":"comment_id","in":"query","required":false,"description":"The target comment's numeric id (the `cid` from the comments endpoint). Requires `post_url`.","schema":{"type":"string"}},{"name":"parent_comment_id","in":"query","required":false,"description":"The parent comment's numeric id — supply this when the target is a reply so it can be resolved directly via the native replies endpoint.","schema":{"type":"string"}},{"name":"author_username","in":"query","required":false,"description":"Return up to `max` comments authored by this username (no comment id needed). Mutually exclusive with `text_contains` and any comment id.","schema":{"type":"string"}},{"name":"text_contains","in":"query","required":false,"description":"Return up to `max` comments whose text contains this snippet (case-insensitive). Mutually exclusive with `author_username` and any comment id.","schema":{"type":"string"}},{"name":"deep_scan","in":"query","required":false,"description":"Widen the scan budget for deeply-buried comments (raises the page ceiling and deadline). Bills 6 credits instead of 2.","schema":{"type":"boolean"}},{"name":"position_hint","in":"query","required":false,"description":"Opaque token from a prior lookup's `lookup.position_hint`. Passing it back probes the comment's last-known location first, making a re-check of an already-found comment cheap.","schema":{"type":"string"}},{"name":"max","in":"query","required":false,"description":"For `author_username`/`text_contains` search: max matches to return (1–20, default 5).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"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`."}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/comment","data":{"comment":{"id":"7654640784985211670","url":"https://www.tiktok.com/@mrbeast/video/7654638524729216287?comment_id=7654640784985211670","parent_id":null,"post_id":"7654638524729216287","text":"[ステッカー] Usain bolt prime","author":{"username":"viktorpalmcrantz","display_name":"Coolpro1023","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/aefcdd0d1f58ac22f5dec6c0835a48df~tplv-tiktokx-cropcenter:100:100.jpg?dr=9640&refresh_token=eb12c336&x-expires=1783202400&x-signature=YDkr9lrMW0EuDYlWhzeOseHRjGg%3D&t=4d5b0474&ps=13740610&shp=30310797&shcp=ff37627b&idc=useast5","verified":false},"engagement":{"likes":20370,"replies":49},"flags":{"pinned":false,"deleted":false},"published_at":"2026-06-23T17:15:54.000Z","ext":{"published_at_epoch":1782234954}},"lookup":{"found_via":"id_scan","pages_fetched":5,"comments_scanned":100,"sort_basis":"top","position_hint":"eyJ2IjoxLCJwbGF0Zm9ybSI6InRpa3RvayIsImN1cnNvciI6MH0"}},"credits_used":2,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/search":{"get":{"summary":"Search TikTok videos by keyword","description":"Searches TikTok for videos matching a keyword query. Returns a list of matching videos with view counts, like counts, captions, author info, and thumbnails.","tags":["tiktok"],"operationId":"get_tiktok_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find TikTok videos","schema":{"type":"string"},"example":"cooking recipes"},{"name":"date_posted","in":"query","required":false,"description":"Time Frame","schema":{"type":"string","enum":["yesterday","this-week","this-month","last-3-months","last-6-months","all-time"]}},{"name":"sort_by","in":"query","required":false,"description":"Sort by","schema":{"type":"string","enum":["relevance","most-liked","date-posted"]}},{"name":"region","in":"query","required":false,"description":"Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more videos. Get 'cursor' from previous response.","schema":{"type":"integer"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/profile":{"get":{"summary":"Get Instagram user profile","description":"Returns public profile information for an Instagram user including follower count, following count, post count, bio, profile picture URL, and verification status.","tags":["instagram"],"operationId":"get_instagram_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Instagram username without the @ symbol","schema":{"type":"string"},"example":"instagram"},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/profile/posts":{"get":{"summary":"List Instagram user posts","description":"Returns a list of recent posts from an Instagram user's profile. Each post includes like count, comment count, caption, media URL, media type, and timestamp. Note: engagement.shares is null on this endpoint (the upstream carries no per-post share count); to additionally merge in per-post share counts where a second source exposes them (coverage varies by account), use /v1/instagram/profile/posts/full.","tags":["instagram"],"operationId":"get_instagram_profile_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Instagram username without the @ symbol","schema":{"type":"string"},"example":"instagram"},{"name":"next_max_id","in":"query","required":false,"description":"Cursor to get next page of results.","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/post":{"get":{"summary":"Get Instagram post details","description":"Returns detailed information about a specific Instagram post including like count, comment count, caption, media URLs, media type, author info, and tagged users.","tags":["instagram"],"operationId":"get_instagram_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Instagram post","schema":{"type":"string"},"example":"https://www.instagram.com/p/CwA1234abcd/"},{"name":"region","in":"query","required":false,"description":"2 letter country code to set the proxy in","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"download_media","in":"query","required":false,"description":"Set to true to also download the video/images and get back permanent, durable media URLs under `data.post.ext.download_media_urls` (`[{ post_id, cdn_url, type, cached }]`). Use these for archiving — the raw `media_urls` are short-lived signed CDN links that expire. Adds a few seconds of latency while the media is fetched.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/post/comments":{"get":{"summary":"List Instagram post comments","description":"Returns a list of comments on an Instagram post, ranked by the platform's own popularity order by default (`sort=top`) so the most-liked comments come first, or newest-first with `sort=recent`. Each comment includes the author, comment text, real like count, reply count, and creation timestamp. Page through with `cursor`.","tags":["instagram"],"operationId":"get_instagram_post_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"URL of the Instagram post (a /p/, /reel/, /reels/, or /tv/ link).","schema":{"type":"string"},"example":"https://www.instagram.com/p/DXidPIVDU6M/"},{"name":"sort","in":"query","required":false,"description":"Ordering: `top` (default) ranks by Instagram's popularity order (most-liked first); `recent` returns newest-first.","schema":{"type":"string","enum":["top","recent"]}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe profile picture links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/comment":{"get":{"summary":"Look up one Instagram comment by URL or id","description":"Resolves a single Instagram comment to a live comment object (current like count, reply count, author, timestamp) without you paginating the comment section. Pass `comment_url` (an `https://www.instagram.com/p/{shortcode}/c/{commentId}/` permalink — reply permalinks `.../c/{parent}/r/{reply}/` are best-effort) OR `post_url` + `comment_id`. Instead of a comment id you can search the comment section: `author_username` or `text_contains` return up to `max` matches. The response includes `lookup.post_comment_count` (the post's true total, so you can reason about scan coverage) and a `lookup.position_hint` — pass it back on a later lookup to make the re-check cheap. Instagram does not expose pinned status or full reply threads to any provider, so `flags.pinned` stays null and deep reply lookups can return `reply_not_resolvable`. Flat 5 credits (15 with `deep_scan=true`); a not-found returns 404 and is fully refunded.","tags":["instagram"],"operationId":"get_instagram_comment","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"comment_url","in":"query","required":false,"description":"An Instagram comment permalink: `https://www.instagram.com/p/{shortcode}/c/{commentId}/` (or a reply permalink `.../c/{parent}/r/{reply}/`, best-effort). Mutually exclusive with `post_url`+`comment_id`.","schema":{"type":"string"},"example":"https://www.instagram.com/p/CnpPou9hWqq/c/18007013966365752/"},{"name":"post_url","in":"query","required":false,"description":"The post URL (a `/p/`, `/reel/`, `/reels/`, or `/tv/` link). Combine with `comment_id`, or with `author_username`/`text_contains` for a search.","schema":{"type":"string"}},{"name":"comment_id","in":"query","required":false,"description":"The target comment's numeric id (`pk`). Requires `post_url`.","schema":{"type":"string"}},{"name":"author_username","in":"query","required":false,"description":"Return up to `max` comments authored by this username (no comment id needed). Mutually exclusive with `text_contains` and any comment id.","schema":{"type":"string"}},{"name":"text_contains","in":"query","required":false,"description":"Return up to `max` comments whose text contains this snippet (case-insensitive). Mutually exclusive with `author_username` and any comment id.","schema":{"type":"string"}},{"name":"deep_scan","in":"query","required":false,"description":"Widen the scan budget for deeply-buried comments (raises the per-chain page ceiling and deadline). Bills 15 credits instead of 5.","schema":{"type":"boolean"}},{"name":"position_hint","in":"query","required":false,"description":"Opaque token from a prior lookup's `lookup.position_hint`. Passing it back replays just the last-known sort chain first, making a re-check of an already-found comment cheap.","schema":{"type":"string"}},{"name":"max","in":"query","required":false,"description":"For `author_username`/`text_contains` search: max matches to return (1–20, default 5).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"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`."}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/comment","data":{"comment":{"id":"7654640784985211670","url":"https://www.tiktok.com/@mrbeast/video/7654638524729216287?comment_id=7654640784985211670","parent_id":null,"post_id":"7654638524729216287","text":"[ステッカー] Usain bolt prime","author":{"username":"viktorpalmcrantz","display_name":"Coolpro1023","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/aefcdd0d1f58ac22f5dec6c0835a48df~tplv-tiktokx-cropcenter:100:100.jpg?dr=9640&refresh_token=eb12c336&x-expires=1783202400&x-signature=YDkr9lrMW0EuDYlWhzeOseHRjGg%3D&t=4d5b0474&ps=13740610&shp=30310797&shcp=ff37627b&idc=useast5","verified":false},"engagement":{"likes":20370,"replies":49},"flags":{"pinned":false,"deleted":false},"published_at":"2026-06-23T17:15:54.000Z","ext":{"published_at_epoch":1782234954}},"lookup":{"found_via":"id_scan","pages_fetched":5,"comments_scanned":100,"sort_basis":"top","position_hint":"eyJ2IjoxLCJwbGF0Zm9ybSI6InRpa3RvayIsImN1cnNvciI6MH0"}},"credits_used":2,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/channel":{"get":{"summary":"Get YouTube channel info","description":"Returns public channel information for a YouTube channel including subscriber count, total video count, total view count, channel description, banner URL, and avatar URL.","tags":["youtube"],"operationId":"get_youtube_channel","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["channelId","handle","url"]],"parameters":[{"name":"channelId","in":"query","required":false,"description":"YouTube channel ID. Can pass a channelId, handle or url (one of: channelId, handle, url — at least one required)","schema":{"type":"string"}},{"name":"handle","in":"query","required":false,"description":"YouTube channel handle without the @ symbol (one of: channelId, handle, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"YouTube channel URL. Can pass a channelId, handle or url (one of: channelId, handle, url — at least one required)","schema":{"type":"string"}},{"name":"hl","in":"query","required":false,"description":"Preferred response language for localized text (ISO 639-1, e.g. 'en', 'es', 'fr').","schema":{"type":"string"}},{"name":"forUsername","in":"query","required":false,"description":"Legacy YouTube username (pre-handle) to look up.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/channel/videos":{"get":{"summary":"List YouTube channel videos","description":"Returns a list of recent videos published by a YouTube channel. Each video includes title, view count, like count, comment count, duration, thumbnail URL, and publish date.","tags":["youtube"],"operationId":"get_youtube_channel_videos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["channelId","handle"]],"parameters":[{"name":"channelId","in":"query","required":false,"description":"YouTube channel ID (one of: channelId, handle — at least one required)","schema":{"type":"string"}},{"name":"handle","in":"query","required":false,"description":"YouTube channel handle without the @ symbol (one of: channelId, handle — at least one required)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by latest or popular","schema":{"type":"string","enum":["latest","popular"]}},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token to get more videos. Get 'continuationToken' from previous response.","schema":{"type":"string"}},{"name":"includeExtras","in":"query","required":false,"description":"This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. This will slow down the response slightly.","schema":{"type":"string"}},{"name":"is_paid_promotions","in":"query","required":false,"description":"Set to 'true' to search YouTube's public paid product placement / sponsorship / endorsement surface — returns normal videos where the creator disclosed a paid promotion.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video":{"get":{"summary":"Get YouTube video details","description":"Returns detailed information about a specific YouTube video including title, view count, like count, comment count, description, tags, duration, channel info, and publish date.","tags":["youtube"],"operationId":"get_youtube_video","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},{"name":"language","in":"query","required":false,"description":"Preferred response language (mapped to Accept-Language header; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc.","schema":{"type":"string"}},{"name":"hl","in":"query","required":false,"description":"Preferred response language for localized text (ISO 639-1, e.g. 'en', 'es', 'fr').","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/videos":{"post":{"summary":"Batch get YouTube video details (up to 1000)","description":"Fetches full details for up to 1000 YouTube videos by id in a single POST request. Each item is the same unified video object as GET /v1/youtube/video. Body: { ids: string[], includeLocalizations?: boolean }. Metered per 50-id chunk.","tags":["youtube"],"operationId":"post_youtube_videos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"hl","in":"query","required":false,"description":"Preferred response language for localized text (ISO 639-1, e.g. 'en', 'ko').","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for youtube/videos. Required: ids.","content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"include_localizations":{"type":"boolean"}},"required":["ids"]}}}}}},"/youtube/channels":{"post":{"summary":"Batch get YouTube channel details (up to 1000)","description":"Fetches full details for up to 1000 YouTube channels by id in a single POST request. Each item is the unified channel (author) object. Body: { ids: string[], includeLocalizations?: boolean }. Metered per 50-id chunk.","tags":["youtube"],"operationId":"post_youtube_channels","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"hl","in":"query","required":false,"description":"Preferred response language for localized text (ISO 639-1, e.g. 'en', 'ko').","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for youtube/channels. Required: ids.","content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"include_localizations":{"type":"boolean"}},"required":["ids"]}}}}}},"/youtube/transcripts":{"post":{"summary":"Up to 100 YouTube video ids → one transcript per row, failed ids refunded.","description":"Batch transcript lookup for LLM corpora. POST a JSON body with an `ids` array of 1–100 BARE 11-character YouTube video ids (full watch URLs are not accepted here — use GET /v1/youtube/video/transcript for a single URL); returns one row per id — the transcript (`format: \"text\"` joins it into one string; `format: \"segments\"` returns `[{start_ms, duration_ms, text}]`), the resolved `language`, and a `status` of ok / not_found / error / deferred — in input order. Optional `language` picks a preferred caption track. Per-id isolation: one caption-less or deleted video never fails the batch — a caption-less video is `not_found` with `ext.reason: \"no_captions\"`, a deleted/unavailable one is `not_found` with `ext.reason: \"video_gone\"`. Billing is per successful row at 3 credits (the single-transcript registry tier); not_found / errored / deferred rows are refunded, so you pay exactly for the transcripts you got. Never cached. Optionally streams Server-Sent Events when the client sends `Accept: text/event-stream`.","tags":["youtube"],"operationId":"post_youtube_transcripts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":3,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}},"requestBody":{"required":true,"description":"JSON body for youtube/transcripts. Required: ids.","content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"language":{"type":"string"},"format":{"type":"string"}},"required":["ids"]}}}}}},"/youtube/video/sponsors":{"get":{"summary":"Detect sponsors of a YouTube video","description":"Checks a YouTube video for the paid-promotion disclosure and infers likely sponsors/promoted brands from the public description, description links, promo-code text, and transcript. Experimental upstream — sponsor attribution is inferred, with per-sponsor confidence and evidence.","tags":["youtube"],"operationId":"get_youtube_video_sponsors","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video or short","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=AVO0ifle-OU"},{"name":"language","in":"query","required":false,"description":"2 letter language code used for transcript lookup, ie 'en', 'es', 'fr' etc.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video/comments":{"get":{"summary":"List YouTube video comments","description":"Returns a list of comments on a specific YouTube video. Each comment includes the author name, comment text, like count, reply count, and publish timestamp.","tags":["youtube"],"operationId":"get_youtube_video_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video to fetch comments for","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token to get more comments. Get 'continuationToken' from previous response.","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"Order of comments","schema":{"type":"string","enum":["top","newest"]}},{"name":"searchTerm","in":"query","required":false,"description":"Filter comments to those containing this search term.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Text format for comment bodies — 'html' (default) or 'plainText'.","schema":{"type":"string","enum":["html","plainText"]}},{"name":"max_results","in":"query","required":false,"description":"Maximum number of comments to return per page.","schema":{"type":"integer"}},{"name":"channel_id","in":"query","required":false,"description":"YouTube channel id to fetch channel-level community comments for (instead of a video's comments).","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video/comment/replies":{"get":{"summary":"List YouTube comment replies","description":"Fetches replies to a specific comment on a YouTube video. Each reply includes text content, author details, like count, and publish date. Requires a continuationToken from the Comments endpoint.","tags":["youtube"],"operationId":"get_youtube_video_comment_replies","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"continuationToken","in":"query","required":true,"description":"Continuation token for the comment replies. Use 'repliesContinuationToken' from the Comments endpoint, or 'continuationToken' from a previous replies response to paginate.","schema":{"type":"string"},"example":"Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIa..."},{"name":"format","in":"query","required":false,"description":"Text format for reply bodies — 'html' (default) or 'plainText'.","schema":{"type":"string","enum":["html","plainText"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/search":{"get":{"summary":"Search YouTube","description":"Searches YouTube by keyword. Returns matching videos, channels, playlists, shorts, shelves, and live streams. Each video result includes title, URL, thumbnail, view count, publish date, duration, channel info, and badges. Filter by `type` to scope to one content kind; filter by `duration` for video length (videos only — not shorts).","tags":["youtube"],"operationId":"get_youtube_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase.","schema":{"type":"string"},"example":"javascript tutorial"},{"name":"uploadDate","in":"query","required":false,"description":"Upload date filter.","schema":{"type":"string","enum":["today","this_week","this_month","this_year"]}},{"name":"sortBy","in":"query","required":false,"description":"Sort order — relevance or popular.","schema":{"type":"string","enum":["relevance","popular"]}},{"name":"type","in":"query","required":false,"description":"Type of content to return.","schema":{"type":"string","enum":["videos","shorts","channels","playlists"]},"example":"videos"},{"name":"duration","in":"query","required":false,"description":"Video duration filter. Only applies to videos (not shorts).","schema":{"type":"string","enum":["under_3_min","between_3_and_20_min","over_20_min"]}},{"name":"region","in":"query","required":false,"description":"2-letter country code of the country to put the proxy in.","schema":{"type":"string"}},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token to get more results. Get `continuationToken` from a previous response.","schema":{"type":"string"}},{"name":"includeExtras","in":"query","required":false,"description":"Set to `true` to include like + comment count and description. For full per-video details use `/v1/youtube/video`. Slows the response slightly.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitter/profile":{"get":{"summary":"Get Twitter user profile","description":"Returns public profile information for a Twitter/X user including follower count, following count, tweet count, bio, profile image URL, banner URL, and verification status.","tags":["twitter"],"operationId":"get_twitter_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Twitter username without the @ symbol","schema":{"type":"string"},"example":"elonmusk"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitter/user/tweets":{"get":{"summary":"List Twitter user tweets","description":"Returns up to the 100 most recent tweets posted by a Twitter/X user. Each tweet includes the full text, like count, retweet count, reply count, media attachments, and creation timestamp. Pagination is not currently supported on this endpoint — the upstream provider returns a single page. For deeper history, combine this with `/v1/twitter/ai-search` or `/v1/search/everywhere`.","tags":["twitter"],"operationId":"get_twitter_user_tweets","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Twitter username without the @ symbol","schema":{"type":"string"},"example":"elonmusk"},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitter/tweet":{"get":{"summary":"Get Twitter tweet details","description":"Returns detailed information about a specific tweet including the full text, like count, retweet count, reply count, quote count, media attachments, author info, and creation timestamp.","tags":["twitter"],"operationId":"get_twitter_tweet","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the tweet","schema":{"type":"string"},"example":"https://x.com/elonmusk/status/1234567890"},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile":{"get":{"summary":"Get LinkedIn user profile","description":"Returns public profile information for a LinkedIn user including name, headline, summary, location, current company, education, skills, and profile picture URL.","tags":["linkedin"],"operationId":"get_linkedin_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile page","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/company":{"get":{"summary":"Get LinkedIn company page","description":"Returns public information about a LinkedIn company page including company name, description, industry, employee count, headquarters location, website, and logo URL.","tags":["linkedin"],"operationId":"get_linkedin_company","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn company page","schema":{"type":"string"},"example":"https://www.linkedin.com/company/microsoft/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/post":{"get":{"summary":"Get LinkedIn post details","description":"Returns detailed information about a specific LinkedIn post including the post text, like count, comment count, share count, author info, media attachments, and publish timestamp.","tags":["linkedin"],"operationId":"get_linkedin_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn post","schema":{"type":"string"},"example":"https://www.linkedin.com/posts/williamhgates_example-activity-1234567890"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/search/people":{"get":{"summary":"Search LinkedIn people","description":"Searches LinkedIn members by name and B2B filters (title, current/past company, school, industry, location, language). Returns a paginated list of matching profiles with handle, headline, location, follower count, and the member URN for follow-up enrichment calls.","tags":["linkedin"],"operationId":"get_linkedin_search_people","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"query","in":"query","required":true,"description":"Name or display-name keyword to search for (e.g. 'Bill Gates').","schema":{"type":"string"},"example":"Bill Gates"},{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"string"}},{"name":"first_name","in":"query","required":false,"description":"Filter by first name.","schema":{"type":"string"}},{"name":"last_name","in":"query","required":false,"description":"Filter by last name.","schema":{"type":"string"}},{"name":"title","in":"query","required":false,"description":"Filter by job title or headline.","schema":{"type":"string"}},{"name":"current_company","in":"query","required":false,"description":"Filter by current company ID (comma-separated for multiple).","schema":{"type":"string"}},{"name":"past_company","in":"query","required":false,"description":"Filter by a previously-worked company ID.","schema":{"type":"string"}},{"name":"school","in":"query","required":false,"description":"Filter by school ID.","schema":{"type":"string"}},{"name":"industry","in":"query","required":false,"description":"Filter by industry ID.","schema":{"type":"string"}},{"name":"geocode_location","in":"query","required":false,"description":"Filter by location geocode ID.","schema":{"type":"string"}},{"name":"profile_language","in":"query","required":false,"description":"Filter by profile language (ISO 2-letter code, e.g. 'en').","schema":{"type":"string"}},{"name":"service_category","in":"query","required":false,"description":"Filter by service-category ID.","schema":{"type":"string"}},{"name":"follower_of","in":"query","required":false,"description":"Return people who follow a specific member URN.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/company/people":{"get":{"summary":"List people at a LinkedIn company","description":"Returns a paginated list of members who work at a company, with handle, headline, location, and member URN. Get the company_id from /v1/linkedin/company.","tags":["linkedin"],"operationId":"get_linkedin_company_people","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"company_id","in":"query","required":true,"description":"LinkedIn numeric company ID (from /v1/linkedin/company).","schema":{"type":"string"},"example":"1035"},{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/post/comments":{"get":{"summary":"Get LinkedIn post comments","description":"Returns a paginated list of comments on a LinkedIn post, with commenter identity, text, reaction breakdown, pin/edit flags, and reply counts.","tags":["linkedin"],"operationId":"get_linkedin_post_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn post (or its activity id).","schema":{"type":"string"},"example":"https://www.linkedin.com/feed/update/urn:li:activity:7244804629786419202"},{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"string"}},{"name":"post_type","in":"query","required":false,"description":"Upstream post type: 'activity' (default) or 'ugc'.","schema":{"type":"string"}},{"name":"sort_order","in":"query","required":false,"description":"Comment ordering: 'relevance' or 'recent'.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/posts":{"get":{"summary":"List a LinkedIn member's posts","description":"List a LinkedIn member's posts — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"cursor","in":"query","required":false,"description":"cursor","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/reactions":{"get":{"summary":"List posts a LinkedIn member reacted to","description":"List posts a LinkedIn member reacted to — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_reactions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"cursor","in":"query","required":false,"description":"cursor","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/post/reposts":{"get":{"summary":"List reposts of a LinkedIn post","description":"List reposts of a LinkedIn post — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_post_reposts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"cursor","in":"query","required":false,"description":"cursor","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/group/posts":{"get":{"summary":"List posts in a LinkedIn group","description":"List posts in a LinkedIn group — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_group_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"group_id","in":"query","required":true,"description":"LinkedIn numeric group ID.","schema":{"type":"string"},"example":"62438"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/company/affiliated-pages":{"get":{"summary":"List a company's affiliated/showcase pages","description":"List a company's affiliated/showcase pages — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_company_affiliated_pages","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"company_id","in":"query","required":true,"description":"LinkedIn numeric company ID (from /v1/linkedin/company).","schema":{"type":"string"},"example":"1035"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/post/comments/replies":{"get":{"summary":"List replies to a LinkedIn comment","description":"List replies to a LinkedIn comment — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_post_comments_replies","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"comment_id","in":"query","required":true,"description":"LinkedIn comment ID (from /post/comments).","schema":{"type":"string"},"example":"7244804629786419202"},{"name":"cursor","in":"query","required":false,"description":"cursor","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/experiences":{"get":{"summary":"List a member's work experiences","description":"List a member's work experiences — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_experiences","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/educations":{"get":{"summary":"List a member's education history","description":"List a member's education history — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_educations","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/skills":{"get":{"summary":"List a member's skills","description":"List a member's skills — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_skills","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/honors":{"get":{"summary":"List a member's honors and awards","description":"List a member's honors and awards — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_honors","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/certifications":{"get":{"summary":"List a member's licenses and certifications","description":"List a member's licenses and certifications — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_certifications","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/publications":{"get":{"summary":"List a member's publications","description":"List a member's publications — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_publications","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/volunteers":{"get":{"summary":"List a member's volunteer experiences","description":"List a member's volunteer experiences — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_volunteers","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/recommendations":{"get":{"summary":"List recommendations for a member","description":"List recommendations for a member — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_recommendations","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"type","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/interests/companies":{"get":{"summary":"List companies a member follows","description":"List companies a member follows — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_interests_companies","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/interests/groups":{"get":{"summary":"List groups a member follows","description":"List groups a member follows — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_interests_groups","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/images":{"get":{"summary":"List a member's image posts","description":"List a member's image posts — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_images","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"cursor","in":"query","required":false,"description":"cursor","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/videos":{"get":{"summary":"List a member's video posts","description":"List a member's video posts — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_videos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"cursor","in":"query","required":false,"description":"cursor","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/comments":{"get":{"summary":"List a member's comments","description":"List a member's comments — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"cursor","in":"query","required":false,"description":"cursor","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/post/reactions":{"get":{"summary":"List reactors on a LinkedIn post","description":"List reactors on a LinkedIn post — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_post_reactions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"type","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/company/jobs":{"get":{"summary":"List a company's job postings","description":"List a company's job postings — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_company_jobs","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"company_id","in":"query","required":true,"description":"LinkedIn numeric company ID (from /v1/linkedin/company).","schema":{"type":"string"},"example":"1035"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"date_posted","in":"query","required":false,"description":"date_posted","schema":{"type":"string"}},{"name":"experience_level","in":"query","required":false,"description":"experience_level","schema":{"type":"string"}},{"name":"job_type","in":"query","required":false,"description":"job_type","schema":{"type":"string"}},{"name":"remote","in":"query","required":false,"description":"remote","schema":{"type":"string"}},{"name":"easy_apply","in":"query","required":false,"description":"easy_apply","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"sort_by","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical job wrappers ({ job })","items":{"type":"object","description":"Canonical job wrapper","properties":{"job":{"type":"object","description":"Nested object: job","properties":{"id":{"type":"string","description":"String at job.id"},"title":{"type":["string","null"],"description":"String at job.title"},"url":{"type":["string","null"],"description":"String at job.url"},"company":{"type":"object","description":"Nested object: job.company","properties":{"id":{"type":["string","null"],"description":"String at job.company.id"},"name":{"type":["string","null"],"description":"String at job.company.name"},"url":{"type":["string","null"],"description":"String at job.company.url"},"verified":{"type":["boolean","null"],"description":"Boolean at job.company.verified"}}},"location":{"type":["string","null"],"description":"String at job.location"},"listed_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"easy_apply":{"type":["boolean","null"],"description":"Boolean at job.easy_apply"},"remote":{"type":["string","null"],"description":"String at job.remote"},"employment_type":{"type":["string","null"],"description":"String at job.employment_type"},"experience_level":{"type":["string","null"],"description":"String at job.experience_level"},"description":{"type":["string","null"],"description":"String at job.description"},"apply_url":{"type":["string","null"],"description":"String at job.apply_url"},"ext":{"type":["object","null"],"description":"Nested object: job.ext","properties":{"is_promote":{"type":["boolean","null"],"description":"Boolean at job.ext.is_promote"},"applicant_count":{"type":["integer","null"],"description":"Numeric at job.ext.applicant_count"},"skills":{"type":["array","null"],"description":"Array at job.ext.skills","items":{"type":"string","description":"String at job.ext.skills"}}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/search/jobs":{"get":{"summary":"Search LinkedIn jobs","description":"Search LinkedIn jobs — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_search_jobs","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword.","schema":{"type":"string"},"example":"marketing"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"date_posted","in":"query","required":false,"description":"date_posted","schema":{"type":"string"}},{"name":"experience_level","in":"query","required":false,"description":"experience_level","schema":{"type":"string"}},{"name":"job_type","in":"query","required":false,"description":"job_type","schema":{"type":"string"}},{"name":"remote","in":"query","required":false,"description":"remote","schema":{"type":"string"}},{"name":"easy_apply","in":"query","required":false,"description":"easy_apply","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"sort_by","schema":{"type":"string"}},{"name":"company","in":"query","required":false,"description":"company","schema":{"type":"string"}},{"name":"geocode","in":"query","required":false,"description":"geocode","schema":{"type":"string"}},{"name":"industry_ids","in":"query","required":false,"description":"industry_ids","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical job wrappers ({ job })","items":{"type":"object","description":"Canonical job wrapper","properties":{"job":{"type":"object","description":"Nested object: job","properties":{"id":{"type":"string","description":"String at job.id"},"title":{"type":["string","null"],"description":"String at job.title"},"url":{"type":["string","null"],"description":"String at job.url"},"company":{"type":"object","description":"Nested object: job.company","properties":{"id":{"type":["string","null"],"description":"String at job.company.id"},"name":{"type":["string","null"],"description":"String at job.company.name"},"url":{"type":["string","null"],"description":"String at job.company.url"},"verified":{"type":["boolean","null"],"description":"Boolean at job.company.verified"}}},"location":{"type":["string","null"],"description":"String at job.location"},"listed_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"easy_apply":{"type":["boolean","null"],"description":"Boolean at job.easy_apply"},"remote":{"type":["string","null"],"description":"String at job.remote"},"employment_type":{"type":["string","null"],"description":"String at job.employment_type"},"experience_level":{"type":["string","null"],"description":"String at job.experience_level"},"description":{"type":["string","null"],"description":"String at job.description"},"apply_url":{"type":["string","null"],"description":"String at job.apply_url"},"ext":{"type":["object","null"],"description":"Nested object: job.ext","properties":{"is_promote":{"type":["boolean","null"],"description":"Boolean at job.ext.is_promote"},"applicant_count":{"type":["integer","null"],"description":"Numeric at job.ext.applicant_count"},"skills":{"type":["array","null"],"description":"Array at job.ext.skills","items":{"type":"string","description":"String at job.ext.skills"}}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/search/location":{"get":{"summary":"Resolve a location to a LinkedIn geocode id","description":"Resolve a location to a LinkedIn geocode id — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_search_location","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword.","schema":{"type":"string"},"example":"marketing"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/search/schools":{"get":{"summary":"Search LinkedIn schools","description":"Search LinkedIn schools — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_search_schools","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword.","schema":{"type":"string"},"example":"marketing"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/search/industry":{"get":{"summary":"Resolve an industry name to a LinkedIn industry id","description":"Resolve an industry name to a LinkedIn industry id — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_search_industry","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword.","schema":{"type":"string"},"example":"marketing"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/about":{"get":{"summary":"Get a member's profile metadata (joined date, freshness)","description":"Get a member's profile metadata (joined date, freshness) — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_about","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/contact":{"get":{"summary":"Get a member's public contact info","description":"Get a member's public contact info — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_contact","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/profile/stats":{"get":{"summary":"Get a member's follower + connection counts","description":"Get a member's follower + connection counts — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_profile_stats","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn profile, company, or post.","schema":{"type":"string"},"example":"https://www.linkedin.com/in/williamhgates/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/company/job-count":{"get":{"summary":"Get a company's open job count","description":"Get a company's open job count — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_company_job_count","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"company_id","in":"query","required":true,"description":"LinkedIn numeric company ID (from /v1/linkedin/company).","schema":{"type":"string"},"example":"1035"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/company/insights":{"get":{"summary":"Get aggregate insights about a company's members","description":"Get aggregate insights about a company's members — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_company_insights","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"company_id","in":"query","required":true,"description":"LinkedIn numeric company ID (from /v1/linkedin/company).","schema":{"type":"string"},"example":"1035"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/group":{"get":{"summary":"Get LinkedIn group details","description":"Get LinkedIn group details — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_group","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"group_id","in":"query","required":true,"description":"LinkedIn numeric group ID.","schema":{"type":"string"},"example":"62438"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/job":{"get":{"summary":"Get LinkedIn job details","description":"Get LinkedIn job details — via the Fresh LinkedIn Scraper upstream, normalised to the SocialCrawl schema.","tags":["linkedin"],"operationId":"get_linkedin_job","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"id","in":"query","required":true,"description":"LinkedIn job ID.","schema":{"type":"string"},"example":"4019392600"},{"name":"include_skills","in":"query","required":false,"description":"include_skills","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"String at job.id"},"title":{"type":["string","null"],"description":"String at job.title"},"url":{"type":["string","null"],"description":"String at job.url"},"company":{"type":"object","description":"Nested object: job.company","properties":{"id":{"type":["string","null"],"description":"String at job.company.id"},"name":{"type":["string","null"],"description":"String at job.company.name"},"url":{"type":["string","null"],"description":"String at job.company.url"},"verified":{"type":["boolean","null"],"description":"Boolean at job.company.verified"}}},"location":{"type":["string","null"],"description":"String at job.location"},"listed_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"easy_apply":{"type":["boolean","null"],"description":"Boolean at job.easy_apply"},"remote":{"type":["string","null"],"description":"String at job.remote"},"employment_type":{"type":["string","null"],"description":"String at job.employment_type"},"experience_level":{"type":["string","null"],"description":"String at job.experience_level"},"description":{"type":["string","null"],"description":"String at job.description"},"apply_url":{"type":["string","null"],"description":"String at job.apply_url"},"ext":{"type":["object","null"],"description":"Nested object: job.ext","properties":{"is_promote":{"type":["boolean","null"],"description":"Boolean at job.ext.is_promote"},"applicant_count":{"type":["integer","null"],"description":"Numeric at job.ext.applicant_count"},"skills":{"type":["array","null"],"description":"Array at job.ext.skills","items":{"type":"string","description":"String at job.ext.skills"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/profile":{"get":{"summary":"Get Facebook page profile","description":"Returns a unified Facebook Author profile with page ID, display name, profile URL, profile image, bio, follower count, and page-like count. `author.following` and `author.posts_count` remain null because the upstream profile response does not provide those totals.","tags":["facebook"],"operationId":"get_facebook_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Facebook page or profile","schema":{"type":"string"},"example":"https://www.facebook.com/Meta"},{"name":"get_business_hours","in":"query","required":false,"description":"Get the business's hours","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/profile/posts":{"get":{"summary":"List Facebook page posts","description":"Returns a list of recent posts from a Facebook page or profile. Each post includes the post text, like count, comment count, share count, media attachments, and publish timestamp.","tags":["facebook"],"operationId":"get_facebook_profile_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["url","pageId"]],"parameters":[{"name":"url","in":"query","required":false,"description":"Full URL of the Facebook page or profile to fetch posts for (one of: url, pageId — at least one required)","schema":{"type":"string"}},{"name":"pageId","in":"query","required":false,"description":"Facebook profile page id (one of: url, pageId — at least one required)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"To paginate through the posts","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/post":{"get":{"summary":"Get Facebook post details","description":"Returns detailed information about a specific Facebook post including the post text, like count, comment count, share count, reactions breakdown, media attachments, and author info.","tags":["facebook"],"operationId":"get_facebook_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Facebook post","schema":{"type":"string"},"example":"https://www.facebook.com/Meta/posts/1234567890"},{"name":"get_comments","in":"query","required":false,"description":"Whether you want to get the first several comments of the post","schema":{"type":"boolean"}},{"name":"get_transcript","in":"query","required":false,"description":"Whether you want to get the transcript of the post","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/post/comments":{"get":{"summary":"List Facebook post comments","description":"Returns a list of comments on a specific Facebook post. Each comment includes the author name, comment text, like count, reply count, and creation timestamp.","tags":["facebook"],"operationId":"get_facebook_post_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["url","feedback_id"]],"parameters":[{"name":"url","in":"query","required":false,"description":"Full URL of the Facebook post to fetch comments for (one of: url, feedback_id — at least one required)","schema":{"type":"string"}},{"name":"feedback_id","in":"query","required":false,"description":"Using feedback_id (instead of url) will *really* speed up the request. You can get the feedback_id when you make a request to /v1/facebook/post. (one of: url, feedback_id — at least one required)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more comments. Get 'cursor' from previous response.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/reddit/subreddit":{"get":{"summary":"List Reddit subreddit posts","description":"Returns a list of top posts from a subreddit. Each post includes the title, score, upvote ratio, comment count, author, flair, permalink, and creation timestamp.","tags":["reddit"],"operationId":"get_reddit_subreddit","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"subreddit","in":"query","required":true,"description":"Subreddit name without the r/ prefix","schema":{"type":"string"},"example":"technology"},{"name":"timeframe","in":"query","required":false,"description":"Timeframe to get posts from. Applied with sort=top (auto-selected when you omit sort).","schema":{"type":"string","enum":["all","day","week","month","year"]}},{"name":"sort","in":"query","required":false,"description":"Sort order","schema":{"type":"string","enum":["best","hot","new","top","rising"]}},{"name":"after","in":"query","required":false,"description":"After to get more posts. Get 'after' from previous response.","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/reddit/subreddit/details":{"get":{"summary":"Get Reddit subreddit details","description":"Returns detailed information about a subreddit including subscriber count, active user count, description, creation date, rules, and subreddit icon URL. Note: the subreddit name is case-sensitive here — pass the subreddit's canonical casing (e.g. `AskReddit`, not `askreddit`). An incorrect casing returns a refunded 404.","tags":["reddit"],"operationId":"get_reddit_subreddit_details","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["subreddit","url"]],"parameters":[{"name":"subreddit","in":"query","required":false,"description":"Subreddit name without the r/ prefix. Case-sensitive — use the subreddit's canonical casing (e.g. `AskReddit`). (one of: subreddit, url — at least one required)","schema":{"type":"string"},"example":"AskReddit"},{"name":"url","in":"query","required":false,"description":"Subreddit URL (one of: subreddit, url — at least one required)","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/reddit/search":{"get":{"summary":"Search Reddit posts","description":"Searches Reddit for posts matching a keyword query. Returns a list of matching posts with titles, scores, comment counts, subreddit names, and permalinks.","tags":["reddit"],"operationId":"get_reddit_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find Reddit posts","schema":{"type":"string"},"example":"best programming languages 2024"},{"name":"sort","in":"query","required":false,"description":"Sort by","schema":{"type":"string","enum":["relevance","new","top","comment_count"]}},{"name":"timeframe","in":"query","required":false,"description":"Timeframe","schema":{"type":"string","enum":["all","day","week","month","year"]}},{"name":"after","in":"query","required":false,"description":"Used to paginate to next page","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/reddit/post/comments":{"get":{"summary":"List Reddit post comments","description":"Returns the full threaded comment tree for a Reddit post. Nested replies are auto-expanded by following upstream pagination, so a single call returns the deep tree (not just top-level comments). Each comment includes the author, body, score, direct-reply count, awards, creation timestamp, and a recursive `replies[]` array. Very large threads are bounded: any branch left unexpanded exposes an `ext.replies_cursor`, and `data.truncated` is true when more remains.","tags":["reddit"],"operationId":"get_reddit_post_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Reddit post to fetch comments for","schema":{"type":"string"},"example":"https://www.reddit.com/r/technology/comments/abc123/example_post/"},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more comments, or replies.","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/threads/profile":{"get":{"summary":"Get Threads user profile","description":"Returns public profile information for a Threads user including follower count, bio, profile picture URL, and verification status.","tags":["threads"],"operationId":"get_threads_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Threads username without the @ symbol","schema":{"type":"string"},"example":"zuck"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/threads/user/posts":{"get":{"summary":"List Threads user posts","description":"Returns the most recent posts from a Threads user (typically ~15 per call). Each post includes the text content, like count, reply count, repost count, media attachments, and creation timestamp. Pagination is not currently supported on this endpoint — the upstream provider returns a single page. For deeper history, use `/v1/threads/search` with a date window or `/v1/search/everywhere`.","tags":["threads"],"operationId":"get_threads_user_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Threads username without the @ symbol","schema":{"type":"string"},"example":"zuck"},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/threads/post":{"get":{"summary":"Get Threads post details","description":"Returns detailed information about a specific Threads post including the text content, like count, reply count, repost count, media attachments, author info, and creation timestamp.","tags":["threads"],"operationId":"get_threads_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Threads post","schema":{"type":"string"},"example":"https://www.threads.net/@zuck/post/CwABCDEFGHI"},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/threads/search":{"get":{"summary":"Search Threads posts","description":"Searches Threads for posts matching a keyword query. Returns a list of matching posts with text content, like counts, author info, and creation timestamps.","tags":["threads"],"operationId":"get_threads_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find Threads posts","schema":{"type":"string"},"example":"artificial intelligence"},{"name":"start_date","in":"query","required":false,"description":"Start date to search for","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"End date to search for","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/pinterest/search":{"get":{"summary":"Search Pinterest pins","description":"Searches Pinterest for pins matching a keyword query. Returns a list of matching pins with titles, image URLs, save counts, author info, and board details.","tags":["pinterest"],"operationId":"get_pinterest_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search query","schema":{"type":"string"},"example":"home decor ideas"},{"name":"cursor","in":"query","required":false,"description":"Cursor","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/pinterest/pin":{"get":{"summary":"Get Pinterest pin details","description":"Returns detailed information about a specific Pinterest pin including the title, description, image URL, save count, comment count, author info, and board details.","tags":["pinterest"],"operationId":"get_pinterest_pin","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Pinterest pin","schema":{"type":"string"},"example":"https://www.pinterest.com/pin/1234567890/"},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitch/profile":{"get":{"summary":"Get Twitch streamer profile","description":"Returns public profile information for a Twitch streamer including display name, follower count, bio, profile image URL, broadcast language, and partner/affiliate status.","tags":["twitch"],"operationId":"get_twitch_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Twitch username","schema":{"type":"string"},"example":"ninja"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitch/clip":{"get":{"summary":"Get Twitch clip details","description":"Returns detailed information about a specific Twitch clip including the title, view count, duration, creator name, broadcaster name, game name, thumbnail URL, and creation timestamp.","tags":["twitch"],"operationId":"get_twitch_clip","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Twitch clip","schema":{"type":"string"},"example":"https://www.twitch.tv/ninja/clip/ExampleClipSlug"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitch/user/videos":{"get":{"summary":"List a Twitch user's videos","description":"Fetches up to 100 videos for a Twitch user — id, slug, URL, embed URL, title, view count, language, duration in seconds, game info, broadcaster details with follower count, thumbnail URL, and available video qualities.","tags":["twitch"],"operationId":"get_twitch_user_videos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Twitch username.","schema":{"type":"string"},"example":"ishowspeed"},{"name":"filter_by","in":"query","required":false,"description":"Filter the returned videos by type — `HIGHLIGHT` or `UPLOAD`. (Archived past broadcasts are not currently available upstream.)","schema":{"type":"string","enum":["HIGHLIGHT","UPLOAD"]}},{"name":"sort_by","in":"query","required":false,"description":"Sort order — `TIME` (newest first) or `VIEWS`.","schema":{"type":"string","enum":["TIME","VIEWS"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitch/user/schedule":{"get":{"summary":"Get a Twitch user's stream schedule","description":"Returns the upcoming stream schedule for a Twitch user — each entry includes start time, end time, title, description, and thumbnail URL.","tags":["twitch"],"operationId":"get_twitch_user_schedule","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Twitch username.","schema":{"type":"string"},"example":"kaicenat"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/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":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Snapchat username","schema":{"type":"string"},"example":"djkhaled305"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/truthsocial/profile":{"get":{"summary":"Get Truth Social user profile","description":"Returns public profile information for a Truth Social user including display name, follower count, following count, truth count, bio, and profile image URL.","tags":["truthsocial"],"operationId":"get_truthsocial_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Truth Social username without the @ symbol","schema":{"type":"string"},"example":"realDonaldTrump"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/truthsocial/user/posts":{"get":{"summary":"List Truth Social user posts","description":"Returns a list of recent truths posted by a Truth Social user. Each truth includes the text content, like count, retruth count, reply count, media attachments, and creation timestamp.","tags":["truthsocial"],"operationId":"get_truthsocial_user_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Truth Social username without the @ symbol (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"realDonaldTrump"},{"name":"user_id","in":"query","required":false,"description":"Truth Social user id. Use this for faster response times. Trumps is 107780257626128497. It is the 'id' field in the profile endpoint. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"next_max_id","in":"query","required":false,"description":"Used to paginate to next page","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/truthsocial/post":{"get":{"summary":"Get Truth Social post details","description":"Returns detailed information about a specific Truth Social post including the text content, like count, retruth count, reply count, media attachments, author info, and creation timestamp.","tags":["truthsocial"],"operationId":"get_truthsocial_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Truth Social post","schema":{"type":"string"},"example":"https://truthsocial.com/@realDonaldTrump/posts/123456789"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/kick/clip":{"get":{"summary":"Get Kick clip details","description":"Returns detailed information about a specific Kick clip including the title, view count, duration, category, creator name, channel name, thumbnail URL, and creation timestamp.","tags":["kick"],"operationId":"get_kick_clip","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Kick clip","schema":{"type":"string"},"example":"https://kick.com/xqc/clips/clip_abc123"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/kwai/profile":{"get":{"summary":"Get a Kwai user profile","description":"Returns public profile data for a Kwai user — username, bio, avatar, verification status, and follower/following/like/post counts. Pass either `handle` or `url`.","tags":["kwai"],"operationId":"get_kwai_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["handle","url"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Kwai profile handle (without the @) (one of: handle, url — at least one required)","schema":{"type":"string"},"example":"KwaiBrasilOficial"},{"name":"url","in":"query","required":false,"description":"Kwai profile URL (one of: handle, url — at least one required)","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/kwai/user/posts":{"get":{"summary":"List a Kwai user's posts","description":"Returns a paginated list of public Kwai posts for a user — captions, media URLs, covers, engagement counts, and author info. Forward the returned `cursor` for the next page. Pass either `handle` or `url`.","tags":["kwai"],"operationId":"get_kwai_user_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["handle","url"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Kwai profile handle (without the @) (one of: handle, url — at least one required)","schema":{"type":"string"},"example":"KwaiBrasilOficial"},{"name":"url","in":"query","required":false,"description":"Kwai profile URL (one of: handle, url — at least one required)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous response for the next page","schema":{"type":"string"}},{"name":"count","in":"query","required":false,"description":"Number of posts to return (max 50)","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/kwai/post":{"get":{"summary":"Get a Kwai post","description":"Returns public Kwai post details — caption, video and cover URLs, view/like/comment/share counts, author info, and music metadata.","tags":["kwai"],"operationId":"get_kwai_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":false,"description":"Full URL of the Kwai post","schema":{"type":"string"},"example":"https://www.kwai.com/@KwaiBrasilOficial/photo/5193363430624671876"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/trending":{"get":{"summary":"Get TikTok trending feed","description":"Returns trending videos for a specific region. Each video includes view count, like count, caption, author info, and thumbnail.","tags":["tiktok"],"operationId":"get_tiktok_trending","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"region","in":"query","required":true,"description":"ISO 3166-1 alpha-2 country code (e.g., US, GB, KR)","schema":{"type":"string"},"example":"US"},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/search/hashtag":{"get":{"summary":"Search TikTok by hashtag","description":"Searches TikTok for videos under a specific hashtag. Returns matching videos with engagement metrics and author info.","tags":["tiktok"],"operationId":"get_tiktok_search_hashtag","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"hashtag","in":"query","required":true,"description":"Hashtag to search for without the # symbol","schema":{"type":"string"},"example":"fyp"},{"name":"region","in":"query","required":false,"description":"Region the proxy will be set to. Note: this isn't going to grab you all tiktoks from this region, you're just setting the proxy there.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more videos. Get 'cursor' from previous response.","schema":{"type":"integer"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/search/top":{"get":{"summary":"TikTok top search results","description":"Returns top search results for a keyword query on TikTok, including accounts, videos, and sounds.","tags":["tiktok"],"operationId":"get_tiktok_search_top","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase","schema":{"type":"string"},"example":"dance challenge"},{"name":"publish_time","in":"query","required":false,"description":"Time Frame TikTok was posted","schema":{"type":"string","enum":["yesterday","this-week","this-month","last-3-months","last-6-months","all-time"]}},{"name":"sort_by","in":"query","required":false,"description":"Sort by","schema":{"type":"string","enum":["relevance","most-liked","date-posted"]}},{"name":"region","in":"query","required":false,"description":"Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more videos. Get 'cursor' from previous response.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/search/users":{"get":{"summary":"Search TikTok users","description":"Searches TikTok for user accounts matching a query. Returns matching profiles with follower counts and verification status.","tags":["tiktok"],"operationId":"get_tiktok_search_users","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find TikTok users","schema":{"type":"string"},"example":"cooking"},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more users. Get 'cursor' from previous response.","schema":{"type":"integer"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/user/audience":{"get":{"summary":"Get TikTok user audience demographics","description":"Returns audience demographic data for a TikTok creator including age distribution, gender split, and top countries.","tags":["tiktok"],"operationId":"get_tiktok_user_audience","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"handle","in":"query","required":true,"description":"TikTok username without the @ symbol","schema":{"type":"string"},"example":"charlidamelio"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"audienceLocations":{"type":["array","null"],"description":"Geographic distribution of the creator's audience, ordered by size. Passthrough from the upstream provider; present for creators whose platform exposes audience geography.","items":{"type":"object","description":"One country bucket of the audience","properties":{"country":{"type":"string","description":"Country name"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"count":{"type":"integer","description":"Number of audience members in this country"},"percentage":{"type":"string","description":"Share of the audience in this country, formatted as a percent string (e.g. \"22.67%\")"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/user/audience","data":{"audienceLocations":[{"country":"Mexico","countryCode":"MX","count":127,"percentage":"28.22%"},{"country":"Brazil","countryCode":"BR","count":40,"percentage":"8.89%"},{"country":"Philippines","countryCode":"PH","count":36,"percentage":"8.00%"},{"country":"United States","countryCode":"US","count":33,"percentage":"7.33%"},{"country":"Colombia","countryCode":"CO","count":20,"percentage":"4.44%"},{"country":"Argentina","countryCode":"AR","count":16,"percentage":"3.56%"},{"country":"Peru","countryCode":"PE","count":14,"percentage":"3.11%"},{"country":"Venezuela","countryCode":"VE","count":12,"percentage":"2.67%"},{"country":"Ecuador","countryCode":"EC","count":10,"percentage":"2.22%"},{"country":"United Kingdom","countryCode":"GB","count":8,"percentage":"1.78%"},{"country":"Dominican Republic","countryCode":"DO","count":7,"percentage":"1.56%"},{"country":"Iraq","countryCode":"IQ","count":7,"percentage":"1.56%"},{"country":"Chile","countryCode":"CL","count":6,"percentage":"1.33%"},{"country":"Bolivia","countryCode":"BO","count":6,"percentage":"1.33%"},{"country":"Costa Rica","countryCode":"CR","count":5,"percentage":"1.11%"},{"country":"Guatemala","countryCode":"GT","count":5,"percentage":"1.11%"},{"country":"Egypt","countryCode":"EG","count":5,"percentage":"1.11%"},{"country":"Pakistan","countryCode":"PK","count":5,"percentage":"1.11%"},{"country":"Honduras","countryCode":"HN","count":5,"percentage":"1.11%"},{"country":"Germany","countryCode":"DE","count":5,"percentage":"1.11%"},{"country":"Italy","countryCode":"IT","count":4,"percentage":"0.89%"},{"country":"Saudi Arabia","countryCode":"SA","count":4,"percentage":"0.89%"},{"country":"France","countryCode":"FR","count":4,"percentage":"0.89%"},{"country":"Turkey","countryCode":"TR","count":4,"percentage":"0.89%"},{"country":"Israel","countryCode":"IL","count":3,"percentage":"0.67%"},{"country":"China","countryCode":"CN","count":3,"percentage":"0.67%"},{"country":"Canada","countryCode":"CA","count":3,"percentage":"0.67%"},{"country":"South Africa","countryCode":"ZA","count":3,"percentage":"0.67%"},{"country":"El Salvador","countryCode":"SV","count":2,"percentage":"0.44%"},{"country":"Bangladesh","countryCode":"BD","count":2,"percentage":"0.44%"},{"country":"Australia","countryCode":"AU","count":2,"percentage":"0.44%"},{"country":"Azerbaijan","countryCode":"AZ","count":2,"percentage":"0.44%"},{"country":"Nigeria","countryCode":"NG","count":2,"percentage":"0.44%"},{"country":"Spain","countryCode":"ES","count":2,"percentage":"0.44%"},{"country":"Poland","countryCode":"PL","count":2,"percentage":"0.44%"},{"country":"Ivory Coast","countryCode":"CI","count":2,"percentage":"0.44%"},{"country":"Uganda","countryCode":"UG","count":2,"percentage":"0.44%"},{"country":"Morocco","countryCode":"MA","count":2,"percentage":"0.44%"},{"country":"Democratic Republic of the Congo","countryCode":"CD","count":1,"percentage":"0.22%"},{"country":"Panama","countryCode":"PA","count":1,"percentage":"0.22%"},{"country":"Algeria","countryCode":"DZ","count":1,"percentage":"0.22%"},{"country":"Norway","countryCode":"NO","count":1,"percentage":"0.22%"},{"country":"Uruguay","countryCode":"UY","count":1,"percentage":"0.22%"},{"country":"Oman","countryCode":"OM","count":1,"percentage":"0.22%"},{"country":"Afghanistan","countryCode":"AF","count":1,"percentage":"0.22%"},{"country":"Jamaica","countryCode":"JM","count":1,"percentage":"0.22%"},{"country":"Lebanon","countryCode":"LB","count":1,"percentage":"0.22%"},{"country":"Belarus","countryCode":"BY","count":1,"percentage":"0.22%"},{"country":"Benin","countryCode":"BJ","count":1,"percentage":"0.22%"},{"country":"United Arab Emirates","countryCode":"AE","count":1,"percentage":"0.22%"},{"country":"Congo","countryCode":"CG","count":1,"percentage":"0.22%"},{"country":"Portugal","countryCode":"PT","count":1,"percentage":"0.22%"},{"country":"Kenya","countryCode":"KE","count":1,"percentage":"0.22%"},{"country":"Kazakhstan","countryCode":"KZ","count":1,"percentage":"0.22%"},{"country":"Netherlands","countryCode":"NL","count":1,"percentage":"0.22%"},{"country":"Paraguay","countryCode":"PY","count":1,"percentage":"0.22%"},{"country":"New Zealand","countryCode":"NZ","count":1,"percentage":"0.22%"},{"country":"Mali","countryCode":"ML","count":1,"percentage":"0.22%"},{"country":"Belize","countryCode":"BZ","count":1,"percentage":"0.22%"},{"country":"Bosnia and Herzegovina","countryCode":"BA","count":1,"percentage":"0.22%"},{"country":"Ethiopia","countryCode":"ET","count":1,"percentage":"0.22%"},{"country":"Greece","countryCode":"GR","count":1,"percentage":"0.22%"},{"country":"Lithuania","countryCode":"LT","count":1,"percentage":"0.22%"},{"country":"Croatia","countryCode":"HR","count":1,"percentage":"0.22%"},{"country":"Ukraine","countryCode":"UA","count":1,"percentage":"0.22%"},{"country":"Nicaragua","countryCode":"NI","count":1,"percentage":"0.22%"},{"country":"Hungary","countryCode":"HU","count":1,"percentage":"0.22%"},{"country":"Senegal","countryCode":"SN","count":1,"percentage":"0.22%"}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/user/followers":{"get":{"summary":"List TikTok user followers","description":"Returns a list of followers for a TikTok user. Each follower includes username, display name, avatar, and follower count.","tags":["tiktok"],"operationId":"get_tiktok_user_followers","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"TikTok username without the @ symbol (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"stoolpresidente"},{"name":"user_id","in":"query","required":false,"description":"User id. Use this for faster response times. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"min_time","in":"query","required":false,"description":"Used to paginate. Get 'min_time' from previous response.","schema":{"type":"integer"}},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/user/following":{"get":{"summary":"List TikTok user following","description":"Returns a list of accounts that a TikTok user is following. Each account includes username, display name, avatar, and follower count. Pagination is not currently supported on this endpoint — the upstream returns a single page only.","tags":["tiktok"],"operationId":"get_tiktok_user_following","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"TikTok username without the @ symbol","schema":{"type":"string"},"example":"stoolpresidente"},{"name":"trim","in":"query","required":false,"description":"Set to true to get a trimmed response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/user/live":{"get":{"summary":"Get TikTok user live stream","description":"Returns current live stream information for a TikTok user including viewer count, stream title, duration, and gift count.","tags":["tiktok"],"operationId":"get_tiktok_user_live","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"TikTok username without the @ symbol","schema":{"type":"string"},"example":"charlidamelio"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/post/transcript":{"get":{"summary":"Get TikTok video transcript","description":"Returns the transcript of a TikTok video. Supports auto-generated captions and AI-powered transcription as fallback.","tags":["tiktok"],"operationId":"get_tiktok_post_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the TikTok video","schema":{"type":"string"},"example":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602"},{"name":"language","in":"query","required":false,"description":"Language of the transcript. 2 letter language code, ie 'en', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh'","schema":{"type":"string"}},{"name":"use_ai_as_fallback","in":"query","required":false,"description":"Set to 'true' to use AI as a fallback to get the transcript if the transcript is not found. Costs 10 credits to use this feature. And only if the video is under 2 minutes.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/song":{"get":{"summary":"Get TikTok song details","description":"Returns details about a specific TikTok sound/song including title, artist, duration, usage count, and cover image.","tags":["tiktok"],"operationId":"get_tiktok_song","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"clipId","in":"query","required":true,"description":"TikTok sound/song clip ID","schema":{"type":"string"},"example":"7439295283975702544"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/song/videos":{"get":{"summary":"List TikTok videos using a song","description":"Returns videos that use a specific TikTok sound/song. Each video includes engagement metrics, author info, and caption.","tags":["tiktok"],"operationId":"get_tiktok_song_videos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"clipId","in":"query","required":false,"description":"TikTok sound/song clip ID","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"The cursor to get the next page of results.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktok/profile/region":{"get":{"summary":"Get TikTok profile region","description":"Returns the ISO 3166-1 alpha-2 region code for a public TikTok profile (e.g. `US` for United States, `MX` for Mexico). Useful for routing region-locked workflows and deduplicating profiles by country.","tags":["tiktok"],"operationId":"get_tiktok_profile_region","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"TikTok username without the @ symbol","schema":{"type":"string"},"example":"stoolpresidente"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktokshop/product":{"get":{"summary":"Get TikTok Shop product details","description":"Returns detailed information about a TikTok Shop product including price, rating, review count, seller info, and images.","tags":["tiktokshop"],"operationId":"get_tiktokshop_product","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the TikTok Shop product page","schema":{"type":"string"},"example":"https://www.tiktok.com/shop/pdp/goli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo/1729587769570529799"},{"name":"region","in":"query","required":false,"description":"Region the proxy will be set to so you can access products from that country. Use 2 letter country codes like US, GB, FR, etc. For England, don't use UK, use GB.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform product ID (Amazon ASIN / Google Shopping product id)"},"url":{"type":["string","null"],"description":"Direct URL to the product page"},"title":{"type":["string","null"],"description":"Product title"},"description":{"type":["string","null"],"description":"String at product.description"},"seller":{"type":["string","null"],"description":"String at product.seller"},"brand":{"type":["string","null"],"description":"Brand name (cleaned). Null when the platform exposes a seller instead."},"price":{"type":"object","description":"Price block (current, original/list, currency)","properties":{"current":{"type":["integer","null"],"description":"Numeric at product.price.current"},"original":{"type":["integer","null"],"description":"Numeric at product.price.original"},"currency":{"type":["string","null"],"description":"String at product.price.currency"}}},"rating":{"type":"object","description":"Aggregate rating (average + number of ratings)","properties":{"average":{"type":["integer","null"],"description":"Numeric at product.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at product.rating.count"}}},"image_urls":{"type":["string","array","null"],"description":"Primary image URL, or an array of image URLs for products with a gallery.","items":{"type":"string","description":"Primary image URL, or an array of image URLs for products with a gallery."}},"availability":{"type":["string","null"],"description":"Stock/availability string when surfaced"},"reviews_count":{"type":["integer","null"],"description":"Numeric at product.reviews_count"},"features":{"type":["array","null"],"description":"Array at product.features","items":{"type":"string","description":"String at product.features"}},"specifications":{"type":["array","null"],"description":"Array at product.specifications","items":{"type":"object","description":"Nested object: product.specifications","properties":{"group":{"type":["string","null"],"description":"String at product.specifications.group"},"name":{"type":["string","null"],"description":"String at product.specifications.name"},"value":{"type":["string","null"],"description":"String at product.specifications.value"}}}},"variations":{"type":["array","null"],"description":"Array at product.variations","items":{"type":"object","description":"Nested object: product.variations","properties":{"id":{"type":["string","null"],"description":"String at product.variations.id"},"title":{"type":["string","null"],"description":"String at product.variations.title"},"url":{"type":["string","null"],"description":"String at product.variations.url"},"category":{"type":["string","null"],"description":"String at product.variations.category"}}}},"ext":{"type":["object","null"],"description":"Nested object: product.ext","properties":{"gid":{"type":["string","null"],"description":"String at product.ext.gid"},"data_docid":{"type":["string","null"],"description":"String at product.ext.data_docid"},"pvf":{"type":["string","null"],"description":"String at product.ext.pvf"},"seller_id":{"type":["string","null"],"description":"String at product.ext.seller_id"},"sold_count":{"type":["integer","null"],"description":"Numeric at product.ext.sold_count"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktokshop/product/reviews":{"get":{"summary":"List TikTok Shop product reviews","description":"Returns reviews for a TikTok Shop product. Each review includes rating, text, author, and timestamp. Upstream pagination is not currently supported — the `page` parameter doesn't round-trip — so only page 1 is returned.","tags":["tiktokshop"],"operationId":"get_tiktokshop_product_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["url","product_id"]],"parameters":[{"name":"url","in":"query","required":false,"description":"Full URL of the TikTok Shop product page (one of: url, product_id — at least one required)","schema":{"type":"string"},"example":"https://www.tiktok.com/shop/pdp/cat-nail-clipper-by-potaroma-adjustable-sizes-built-in-file-safe-for-kittens-cats/1731578642912612516"},{"name":"product_id","in":"query","required":false,"description":"The ID of the product (required if url is not provided) (one of: url, product_id — at least one required)","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"ISO 3166-1 alpha-2 region for the product (e.g. `US`). Important when the product is regionally scoped.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktokshop/products":{"get":{"summary":"List TikTok Shop products","description":"Returns products from a TikTok Shop page — title, cover images, URL, price info, sold count, review count, and rating. Sort by best-selling (`sort_by=top`) or newest (`sort_by=new_releases`); filter by `region`. Pagination via the upstream `cursor` is not currently exposed — only page 1 is returned.","tags":["tiktokshop"],"operationId":"get_tiktokshop_products","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the TikTok Shop page","schema":{"type":"string"},"example":"https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079"},{"name":"sort_by","in":"query","required":false,"description":"Sort products by best-selling (`top`) or newest (`new_releases`). Defaults to `top`.","schema":{"type":"string","enum":["top","new_releases"]}},{"name":"region","in":"query","required":false,"description":"Region to get shop products from. Defaults to US if not provided.","schema":{"type":"string","enum":["US","GB","DE","FR","IT","ID","MY","MX","PH","SG","ES","TH","VN","BR","JP","IE"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical product wrappers ({ product })","items":{"type":"object","description":"Canonical product wrapper","properties":{"product":{"type":"object","description":"Canonical Product object (unified across commerce platforms)","properties":{"id":{"type":"string","description":"Platform product ID (Amazon ASIN / Google Shopping product id)"},"url":{"type":["string","null"],"description":"Direct URL to the product page"},"title":{"type":["string","null"],"description":"Product title"},"description":{"type":["string","null"],"description":"String at product.description"},"seller":{"type":["string","null"],"description":"String at product.seller"},"brand":{"type":["string","null"],"description":"Brand name (cleaned). Null when the platform exposes a seller instead."},"price":{"type":"object","description":"Price block (current, original/list, currency)","properties":{"current":{"type":["integer","null"],"description":"Numeric at product.price.current"},"original":{"type":["integer","null"],"description":"Numeric at product.price.original"},"currency":{"type":["string","null"],"description":"String at product.price.currency"}}},"rating":{"type":"object","description":"Aggregate rating (average + number of ratings)","properties":{"average":{"type":["integer","null"],"description":"Numeric at product.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at product.rating.count"}}},"image_urls":{"type":["string","array","null"],"description":"Primary image URL, or an array of image URLs for products with a gallery.","items":{"type":"string","description":"Primary image URL, or an array of image URLs for products with a gallery."}},"availability":{"type":["string","null"],"description":"Stock/availability string when surfaced"},"reviews_count":{"type":["integer","null"],"description":"Numeric at product.reviews_count"},"features":{"type":["array","null"],"description":"Array at product.features","items":{"type":"string","description":"String at product.features"}},"specifications":{"type":["array","null"],"description":"Array at product.specifications","items":{"type":"object","description":"Nested object: product.specifications","properties":{"group":{"type":["string","null"],"description":"String at product.specifications.group"},"name":{"type":["string","null"],"description":"String at product.specifications.name"},"value":{"type":["string","null"],"description":"String at product.specifications.value"}}}},"variations":{"type":["array","null"],"description":"Array at product.variations","items":{"type":"object","description":"Nested object: product.variations","properties":{"id":{"type":["string","null"],"description":"String at product.variations.id"},"title":{"type":["string","null"],"description":"String at product.variations.title"},"url":{"type":["string","null"],"description":"String at product.variations.url"},"category":{"type":["string","null"],"description":"String at product.variations.category"}}}},"ext":{"type":["object","null"],"description":"Nested object: product.ext","properties":{"gid":{"type":["string","null"],"description":"String at product.ext.gid"},"data_docid":{"type":["string","null"],"description":"String at product.ext.data_docid"},"pvf":{"type":["string","null"],"description":"String at product.ext.pvf"},"seller_id":{"type":["string","null"],"description":"String at product.ext.seller_id"},"sold_count":{"type":["integer","null"],"description":"Numeric at product.ext.sold_count"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktokshop/search":{"get":{"summary":"Search TikTok Shop products","description":"Searches TikTok Shop for products matching a query. Returns matching products with prices, ratings, and seller info.","tags":["tiktokshop"],"operationId":"get_tiktokshop_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find TikTok Shop products","schema":{"type":"string"},"example":"phone case"},{"name":"page","in":"query","required":false,"description":"Page number to retrieve","schema":{"type":"integer"}},{"name":"region","in":"query","required":false,"description":"Region to search shop products in.","schema":{"type":"string","enum":["US","GB","DE","FR","IT","ID","MY","MX","PH","SG","ES","TH","VN","BR","JP","IE"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tiktokshop/user/showcase":{"get":{"summary":"List TikTok user showcase products","description":"Fetches products featured in a TikTok user's public showcase — the products a creator promotes on their profile. Each product includes title, price, images, and shop details.","tags":["tiktokshop"],"operationId":"get_tiktokshop_user_showcase","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"The handle of the user","schema":{"type":"string"},"example":"mrtiktokreviews"},{"name":"region","in":"query","required":false,"description":"Region to put the proxy in","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"The cursor to the next page of products","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/basic-profile":{"get":{"summary":"Get Instagram basic profile","description":"Returns basic public profile info for an Instagram user by user ID including username, full name, and profile picture.","tags":["instagram"],"operationId":"get_instagram_basic_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"userId","in":"query","required":false,"description":"Instagram numeric user ID","schema":{"type":"string"},"example":"314216"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/profile/reels":{"get":{"summary":"List Instagram user reels","description":"Returns a list of reels posted by an Instagram user. Each reel includes view count, like count, comment count, and thumbnail. Note: engagement.shares is null on this endpoint (the upstream carries no per-post share count); to additionally merge in per-reel share counts where a second source exposes them (coverage varies by account), use /v1/instagram/profile/reels/full.","tags":["instagram"],"operationId":"get_instagram_profile_reels","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["user_id","handle"]],"parameters":[{"name":"user_id","in":"query","required":false,"description":"Instagram user id. Use this for faster response times. (one of: user_id, handle — at least one required)","schema":{"type":"string"}},{"name":"handle","in":"query","required":false,"description":"Instagram username without the @ symbol (one of: user_id, handle — at least one required)","schema":{"type":"string"}},{"name":"max_id","in":"query","required":false,"description":"Max id to get more reels. Get 'max_id' from previous response.","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/highlights":{"get":{"summary":"List Instagram story highlights","description":"Returns a list of story highlight collections for an Instagram user including highlight titles, cover images, and item counts.","tags":["instagram"],"operationId":"get_instagram_highlights","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["user_id","handle"]],"parameters":[{"name":"user_id","in":"query","required":false,"description":"Instagram user id. Use for faster response times. (one of: user_id, handle — at least one required)","schema":{"type":"string"}},{"name":"handle","in":"query","required":false,"description":"Instagram username without the @ symbol (one of: user_id, handle — at least one required)","schema":{"type":"string"},"example":"instagram"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/highlight/detail":{"get":{"summary":"Get Instagram highlight detail","description":"Returns the items within a specific Instagram story highlight including media URLs, timestamps, and interaction counts.","tags":["instagram"],"operationId":"get_instagram_highlight_detail","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"id","in":"query","required":false,"description":"Instagram highlight ID — the numeric id, with or without the `highlight:` prefix. Get it from `/v1/instagram/user/highlights`.","schema":{"type":"string"},"example":"18067016518767507"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/search/reels":{"get":{"summary":"Search Instagram reels","description":"Searches Instagram for reels matching a keyword query. Returns matching reels with view counts, like counts, and author info.","tags":["instagram"],"operationId":"get_instagram_search_reels","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find Instagram reels","schema":{"type":"string"},"example":"workout routine"},{"name":"date_posted","in":"query","required":false,"description":"Date posted","schema":{"type":"string","enum":["last-hour","last-day","last-week","last-month","last-year"]}},{"name":"page","in":"query","required":false,"description":"The page number to return.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/media/transcript":{"get":{"summary":"Get Instagram media transcript","description":"Returns the AI-generated transcript of an Instagram video or reel. Supports auto-generated and AI-powered transcription.","tags":["instagram"],"operationId":"get_instagram_media_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Instagram video or reel","schema":{"type":"string"},"example":"https://www.instagram.com/reel/DHsD6HGqJhp/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/user/embed":{"get":{"summary":"Get Instagram user embed HTML","description":"Returns embeddable HTML snippet for an Instagram user profile that can be embedded on external websites.","tags":["instagram"],"operationId":"get_instagram_user_embed","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Instagram username without the @ symbol","schema":{"type":"string"},"example":"instagram"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/audio/reels":{"get":{"summary":"List Instagram reels using an audio track","description":"Returns reels that use a specific audio track on Instagram. Each reel includes engagement metrics and author info. Forward the returned `cursor` to request the next page.","tags":["instagram"],"operationId":"get_instagram_audio_reels","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"audio_id","in":"query","required":true,"description":"Instagram audio ID — the numeric id from an instagram.com/reels/audio/{audio_id}/ URL","schema":{"type":"string"},"example":"1392969992841787"},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from the previous response","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/search/hashtag":{"get":{"summary":"Search Instagram posts by hashtag","description":"Returns recent public Instagram posts for a hashtag from Instagram's native hashtag feed. Each post includes shortcode, URL, caption, media URLs, engagement counts, and the author. Pass `type` to choose the ranking (`top`, `recent`, or `clips` for reels only) and forward the returned `cursor` to page deeper.","tags":["instagram"],"operationId":"get_instagram_search_hashtag","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"hashtag","in":"query","required":true,"description":"The hashtag to search for. The leading # is optional.","schema":{"type":"string"},"example":"makeup"},{"name":"type","in":"query","required":false,"description":"Ranking of the returned posts: `top` (default), `recent`, or `clips` (reels only).","schema":{"type":"string","enum":["top","recent","clips"]}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe media links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/search/profiles":{"get":{"summary":"Search Instagram profiles by keyword","description":"Searches Google for public Instagram results matching a keyword or phrase, then returns matching public profiles mapped to the unified Author schema — `username`, `display_name`, `bio`, `verified`, `followers`, `following`, `posts_count`, `avatar_url`, and the profile `url`. Best-effort against Google's index, not a native Instagram profile search.","tags":["instagram"],"operationId":"get_instagram_search_profiles","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Bio or caption keyword/phrase to search for.","schema":{"type":"string"},"example":"yoga"},{"name":"cursor","in":"query","required":false,"description":"The cursor returned by the previous response. In this version it is the next Google results page number.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/reels/trending":{"get":{"summary":"Get trending Instagram reels","description":"Fetches trending reels from Instagram's public reels page. Instagram returns a small batch per call and results can overlap, so call repeatedly to discover more — duplicates are expected. Each item includes shortcode, URL, caption, media URLs, engagement counts when exposed, and user info.","tags":["instagram"],"operationId":"get_instagram_reels_trending","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/followers":{"get":{"summary":"List Instagram followers","description":"Returns a paginated list of the accounts that follow an Instagram user. Each follower includes username, display name, avatar URL, verification status, and profile URL. Pass either `handle` or `user_id`, and page through with `cursor`.","tags":["instagram"],"operationId":"get_instagram_followers","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Instagram username without the @ symbol. (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"mrbeast"},{"name":"user_id","in":"query","required":false,"description":"Instagram numeric user ID. Use this for faster responses. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/following":{"get":{"summary":"List Instagram following","description":"Returns a paginated list of the accounts an Instagram user follows. Each account includes username, display name, avatar URL, verification status, and profile URL. Pass either `handle` or `user_id`, and page through with `cursor`.","tags":["instagram"],"operationId":"get_instagram_following","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Instagram username without the @ symbol. (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"mrbeast"},{"name":"user_id","in":"query","required":false,"description":"Instagram numeric user ID. Use this for faster responses. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/similar":{"get":{"summary":"List similar Instagram accounts","description":"Returns a list of Instagram accounts similar to a given user — the related accounts Instagram surfaces as suggestions. Each account includes username, display name, avatar URL, verification status, and profile URL. Pass either `handle` or `user_id`. Passing `user_id` is faster because no username lookup is needed.","tags":["instagram"],"operationId":"get_instagram_similar","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Instagram username without the @ symbol. (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"mrbeast"},{"name":"user_id","in":"query","required":false,"description":"Instagram numeric user ID. Use this for faster responses. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/post/likers":{"get":{"summary":"List Instagram post likers","description":"Returns a paginated list of the accounts that liked an Instagram post. Each liker includes username, display name, avatar URL, verification status, and profile URL, alongside the total like count. Pass the post `url` and page through with `cursor`.","tags":["instagram"],"operationId":"get_instagram_post_likers","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"URL of the Instagram post (a /p/ or /reel/ link).","schema":{"type":"string"},"example":"https://www.instagram.com/p/CnpPou9hWqq/"},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe profile picture links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/post/stats":{"get":{"summary":"Get Instagram post stats including the share count","description":"Returns full engagement stats for a single Instagram post or reel — view (play) count, likes, comments, and the share count (`engagement.shares`), which is the number shown next to the paper-plane Share icon in the app. The share count is a strong authenticity signal: unlike likes and comments, shares are hard to inflate, so it helps separate genuine reach from bought engagement. The standard /v1/instagram/post endpoint cannot return the share count. Use this endpoint for a single post; to get the share count for every reel or post across a whole feed in one call, use /v1/instagram/profile/reels/full or /v1/instagram/profile/posts/full. Note: Instagram's newer two-arrows Repost (\"regram\") counter shown in the mobile app is a separate metric that Instagram does not include in its post data, so no API can return it. Pass the post `url` (a /p/, /reel/, or /tv/ link). `engagement.saves` stays null because Instagram does not expose a numeric save count.","tags":["instagram"],"operationId":"get_instagram_post_stats","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"URL of the Instagram post (a /p/, /reel/, or /tv/ link).","schema":{"type":"string"},"example":"https://www.instagram.com/p/CnpPou9hWqq/"},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe media links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/tagged":{"get":{"summary":"List posts an Instagram user is tagged in","description":"Returns a paginated list of the posts that tag an Instagram user. Each post includes shortcode, URL, caption, media URLs, engagement counts, and the author. Pass either `handle` or `user_id`, and page through with `cursor`.","tags":["instagram"],"operationId":"get_instagram_tagged","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Instagram username without the @ symbol. (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"mrbeast"},{"name":"user_id","in":"query","required":false,"description":"Instagram numeric user ID. Use this for faster responses. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe media links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/location/posts":{"get":{"summary":"List recent posts at an Instagram location","description":"Returns a paginated list of recent posts tagged at an Instagram location. Each post includes shortcode, URL, caption, media URLs, engagement counts, and the author. Pass the `location_id` and page through with `cursor`.","tags":["instagram"],"operationId":"get_instagram_location_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"location_id","in":"query","required":true,"description":"Instagram numeric location ID.","schema":{"type":"string"},"example":"331004901"},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe media links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/engagement":{"get":{"summary":"Get Instagram engagement statistics","description":"Returns computed engagement statistics for an Instagram account based on its recent posts — an overall engagement rate, follower count, total likes and comments across the sampled posts, and a per-post breakdown with likes, comments, post time, and likes/comments-per-hour velocity. Pass the account `handle`.","tags":["instagram"],"operationId":"get_instagram_engagement","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"handle","in":"query","required":true,"description":"Instagram username without the @ symbol.","schema":{"type":"string"},"example":"mrbeast"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/search/location":{"get":{"summary":"Search Instagram locations","description":"Searches Instagram locations by keyword. Returns matching places, each with its location object (id, name, coordinates) plus a display title and subtitle. Use a returned location id with the Instagram location posts endpoint to fetch recent posts tagged there.","tags":["instagram"],"operationId":"get_instagram_search_location","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find Instagram locations.","schema":{"type":"string"},"example":"Paris"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/username-suggestions":{"get":{"summary":"Get Instagram username suggestions","description":"Returns suggested available Instagram usernames derived from a keyword — useful for choosing a new handle. Pass a `query` keyword to seed the suggestions.","tags":["instagram"],"operationId":"get_instagram_username_suggestions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Keyword to seed the username suggestions.","schema":{"type":"string"},"example":"mrbeast"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/search/music":{"get":{"summary":"Search Instagram music","description":"Searches Instagram's audio (music) library by keyword. Returns matching tracks, each with artist and title, audio and cover-artwork URLs, duration, and usage metadata. Page through with `cursor`.","tags":["instagram"],"operationId":"get_instagram_search_music","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find Instagram audio tracks.","schema":{"type":"string"},"example":"beyonce"},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/stories":{"get":{"summary":"List an Instagram user's active stories","description":"Returns the active stories currently in a user's story tray. Each story includes its id, media URLs (image or video), thumbnail, duration, capture time, and the author. Pass either `handle` or `user_id`. Passing `user_id` is faster because no username lookup is needed. A user with no active stories returns an empty list — not an error.","tags":["instagram"],"operationId":"get_instagram_stories","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Instagram username without the @ symbol. (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"instagram"},{"name":"user_id","in":"query","required":false,"description":"Instagram numeric user ID. Use this for faster responses. (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe media links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/story/download":{"get":{"summary":"Download a single Instagram story","description":"Returns the downloadable media for one specific story — the full-resolution image or video URLs and the story's metadata. Pass the `user_id` of the story's author and the `story_id` of the individual story (get story ids from the Instagram stories endpoint).","tags":["instagram"],"operationId":"get_instagram_story_download","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["user_id"],["story_id"]],"parameters":[{"name":"user_id","in":"query","required":false,"description":"Instagram numeric user ID of the story's author. (one of: user_id — at least one required)","schema":{"type":"string"},"example":"25025320"},{"name":"story_id","in":"query","required":false,"description":"ID of the individual story to download. (one of: story_id — at least one required)","schema":{"type":"string"},"example":"3926693776893966474"},{"name":"safe_url","in":"query","required":false,"description":"When true, returns URL-safe media links suitable for embedding.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/instagram/music/trending":{"get":{"summary":"List trending Instagram music","description":"Returns the audio tracks currently trending on Instagram. Each track includes its title, artist, audio and cover-artwork URLs, and usage metadata — useful for spotting sounds to ride for reach. Takes no parameters.","tags":["instagram"],"operationId":"get_instagram_music_trending","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/channel/shorts":{"get":{"summary":"List YouTube channel shorts","description":"Returns a list of YouTube Shorts published by a channel. Each short includes view count, like count, title, and thumbnail.","tags":["youtube"],"operationId":"get_youtube_channel_shorts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["channelId","handle"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"YouTube channel handle without the @ symbol (one of: channelId, handle — at least one required)","schema":{"type":"string"}},{"name":"channelId","in":"query","required":false,"description":"Can pass channelId or handle (one of: channelId, handle — at least one required)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by newest or popular","schema":{"type":"string","enum":["newest","popular"]}},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token to get more videos. Get 'continuationToken' from previous response.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/community-post":{"get":{"summary":"Get YouTube community post","description":"Returns details of a YouTube community post including text content, like count, comment count, images, and author info.","tags":["youtube"],"operationId":"get_youtube_community_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube community post","schema":{"type":"string"},"example":"https://www.youtube.com/post/Ugkxvj2KoApYAXoqLWnKVr6zZe5JjeHrQeP8"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/playlist":{"get":{"summary":"Get YouTube playlist","description":"Returns videos in a YouTube playlist including titles, view counts, durations, thumbnails, and channel info.","tags":["youtube"],"operationId":"get_youtube_playlist","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"playlist_id","in":"query","required":true,"description":"YouTube playlist ID","schema":{"type":"string"},"example":"PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response — fetches the next page.","schema":{"type":"string"}},{"name":"channel_id","in":"query","required":false,"description":"YouTube channel id — pages that channel's uploads instead of a playlist.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/search/hashtag":{"get":{"summary":"Search YouTube by hashtag","description":"Searches YouTube for videos under a specific hashtag. Returns matching videos with view counts, channel info, and publish dates.","tags":["youtube"],"operationId":"get_youtube_search_hashtag","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"hashtag","in":"query","required":true,"description":"Hashtag to search for without the # symbol","schema":{"type":"string"},"example":"shorts"},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token to get more videos. Get 'continuationToken' from previous response.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Search for all types of content or only shorts","schema":{"type":"string","enum":["all","shorts"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/shorts/trending":{"get":{"summary":"Get trending YouTube shorts","description":"Returns currently trending YouTube Shorts with view counts, like counts, channel info, and thumbnails.","tags":["youtube"],"operationId":"get_youtube_shorts_trending","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video/transcript":{"get":{"summary":"Get YouTube video transcript","description":"Returns the transcript of a YouTube video as timestamped segments — each with text, start `offset` and `duration` (seconds), language, word count, and speech rate. Supports multiple languages via `language`.","tags":["youtube"],"operationId":"get_youtube_video_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":3,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},{"name":"language","in":"query","required":false,"description":"2 letter language code, ie 'en', 'es', 'fr' etc. If the transcript is not available in the language you specify, the transcript will be null.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/channel/playlists":{"get":{"summary":"List a YouTube channel's playlists","description":"Fetches playlists from a YouTube channel's Playlists tab — playlist ID, title, thumbnail, video count, channel info, and playlist URL — plus a `continuationToken` when more results are available. Pass `handle` or `channelId` for the first page; forward `continuationToken` for subsequent pages.","tags":["youtube"],"operationId":"get_youtube_channel_playlists","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["channelId","handle"]],"parameters":[{"name":"channelId","in":"query","required":false,"description":"YouTube channel ID. (one of: channelId, handle — at least one required)","schema":{"type":"string"}},{"name":"handle","in":"query","required":false,"description":"YouTube channel handle (with or without @). (one of: channelId, handle — at least one required)","schema":{"type":"string"},"example":"MrBeast"},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token from a previous response — fetches the next page.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/channel/lives":{"get":{"summary":"List a YouTube channel's live streams","description":"Fetches live streams and past streams from a YouTube channel's Live tab — title, URL, thumbnail, view count, publish time, duration — plus a `continuationToken` when more results are available. Pass `handle` or `channelId` for the first page; forward `continuationToken` for subsequent pages.","tags":["youtube"],"operationId":"get_youtube_channel_lives","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["channelId","handle"]],"parameters":[{"name":"channelId","in":"query","required":false,"description":"YouTube channel ID. (one of: channelId, handle — at least one required)","schema":{"type":"string"}},{"name":"handle","in":"query","required":false,"description":"YouTube channel handle (with or without @). (one of: channelId, handle — at least one required)","schema":{"type":"string"},"example":"IShowSpeed"},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token from a previous response — fetches the next page.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/channel/community-posts":{"get":{"summary":"List a YouTube channel's community posts","description":"Fetches community posts from a YouTube channel's Posts tab — post ID, URL, content, images, attached video, like count, publish time, channel info — plus a `continuationToken` when more results are available. Pass `handle` or `channelId` for the first page; forward `continuationToken` for subsequent pages.","tags":["youtube"],"operationId":"get_youtube_channel_community_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["channelId","handle"]],"parameters":[{"name":"channelId","in":"query","required":false,"description":"YouTube channel ID. (one of: channelId, handle — at least one required)","schema":{"type":"string"}},{"name":"handle","in":"query","required":false,"description":"YouTube channel handle (with or without @). (one of: channelId, handle — at least one required)","schema":{"type":"string"},"example":"MrBeast"},{"name":"continuationToken","in":"query","required":false,"description":"Continuation token from a previous response — fetches the next page.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/videos/trending":{"get":{"summary":"Get trending YouTube videos","description":"Returns the most popular (trending) YouTube videos for a region and category — title, thumbnail, duration, view/like/comment counts, channel, and publish time — plus a `cursor` when more results are available. Filter by `region` (ISO country) and `category` (YouTube category id); forward `cursor` for subsequent pages.","tags":["youtube"],"operationId":"get_youtube_videos_trending","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"region","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code (e.g. US, GB, KR).","schema":{"type":"string"},"example":"US"},{"name":"category","in":"query","required":false,"description":"YouTube video category id (e.g. 10 = Music, 24 = Entertainment).","schema":{"type":"string"},"example":"10"},{"name":"language","in":"query","required":false,"description":"Localization language (ISO 639-1) for titles/metadata.","schema":{"type":"string"}},{"name":"max_results","in":"query","required":false,"description":"Maximum number of videos to return (1–50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response — fetches the next page.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/playlist/items":{"get":{"summary":"List the videos in a YouTube playlist","description":"Returns the videos in a YouTube playlist in order — video id, title, thumbnail, owning channel, and publish time — plus a `cursor` when more results are available. Pass `playlist_id` for the first page; forward `cursor` for subsequent pages.","tags":["youtube"],"operationId":"get_youtube_playlist_items","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"playlist_id","in":"query","required":true,"description":"YouTube playlist id (the value after `list=` in a playlist URL).","schema":{"type":"string"},"example":"PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI"},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response — fetches the next page.","schema":{"type":"string"}},{"name":"channel_id","in":"query","required":false,"description":"YouTube channel id — pages that channel's uploads instead of a playlist.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/search/advanced":{"get":{"summary":"Advanced YouTube video search","description":"Searches YouTube videos with the full filter set — sort `order`, `duration`, live/upcoming `event_type`, Creative-Commons `license`, `category`, `region`, `language`, and `published_after`/`published_before` date windows — returning video id, title, thumbnail, channel, and publish time, plus a `cursor` for the next page. Results are always videos.","tags":["youtube"],"operationId":"get_youtube_search_advanced","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search query.","schema":{"type":"string"},"example":"lofi hip hop"},{"name":"order","in":"query","required":false,"description":"Sort order: date, rating, relevance (default), title, videoCount, viewCount.","schema":{"type":"string"}},{"name":"duration","in":"query","required":false,"description":"Video length: short (<4m), medium (4–20m), long (>20m), any.","schema":{"type":"string"},"example":"long"},{"name":"event_type","in":"query","required":false,"description":"Broadcast type: live, upcoming, completed.","schema":{"type":"string"}},{"name":"license","in":"query","required":false,"description":"License filter: creativeCommon, youtube, any.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"YouTube video category id (e.g. 10 = Music).","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Preferred result language (ISO 639-1).","schema":{"type":"string"}},{"name":"published_after","in":"query","required":false,"description":"RFC-3339 datetime lower bound (e.g. 2026-01-01T00:00:00Z).","schema":{"type":"string"}},{"name":"published_before","in":"query","required":false,"description":"RFC-3339 datetime upper bound.","schema":{"type":"string"}},{"name":"channel_id","in":"query","required":false,"description":"Restrict results to a single channel id.","schema":{"type":"string"}},{"name":"max_results","in":"query","required":false,"description":"Maximum number of videos to return (1–50).","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor from a previous response — fetches the next page.","schema":{"type":"string"}},{"name":"safe_search","in":"query","required":false,"description":"Safe-search filter: none, moderate, strict.","schema":{"type":"string"}},{"name":"video_caption","in":"query","required":false,"description":"Caption filter: any, closedCaption, none.","schema":{"type":"string"}},{"name":"video_definition","in":"query","required":false,"description":"Quality filter: any, high, standard.","schema":{"type":"string"}},{"name":"video_dimension","in":"query","required":false,"description":"Dimension filter: 2d, 3d, any.","schema":{"type":"string"}},{"name":"video_embeddable","in":"query","required":false,"description":"Restrict to embeddable videos: true, any.","schema":{"type":"string"}},{"name":"video_type","in":"query","required":false,"description":"Type filter: any, episode, movie.","schema":{"type":"string"}},{"name":"topic_id","in":"query","required":false,"description":"Restrict to a Freebase topic id (e.g. /m/04rlf for music).","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Latitude,longitude center for a geo search (e.g. 37.42307,-122.08427). Must be used together with location_radius.","schema":{"type":"string"}},{"name":"location_radius","in":"query","required":false,"description":"Radius around location with a unit suffix (e.g. 50km, 10mi). Must be used together with location.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/search/suggestions":{"get":{"summary":"Get YouTube search suggestions","description":"Returns YouTube's search autocomplete suggestions for a partial query — the same suggestions the search box shows. Useful for keyword expansion and SEO research. Returns a string list under `items`.","tags":["youtube"],"operationId":"get_youtube_search_suggestions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Partial search query to autocomplete.","schema":{"type":"string"},"example":"lofi"},{"name":"region","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code to localize suggestions.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video/audio":{"get":{"summary":"Get a YouTube video's audio file streams","description":"Returns the downloadable audio stream files for a YouTube video — each with a direct media `url`, mime type, bitrate, audio quality, sample rate, channels, and approximate duration. The stream URLs are time-limited: fetch them immediately and do not cache.","tags":["youtube"],"operationId":"get_youtube_video_audio","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video.","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type — this is a passthrough list, not a canonical object.","items":{"type":"object","description":"A single media file with a direct `url` and type-specific metadata.","properties":{"url":{"type":"string","description":"Direct URL to the media file. Audio/video stream URLs are time-limited — fetch immediately and do not cache."}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video/files":{"get":{"summary":"Get a YouTube video's video file streams","description":"Returns the downloadable video stream files for a YouTube video — each with a direct media `url`, mime type, resolution (`width`/`height`), quality label, fps, bitrate, and approximate duration. The stream URLs are time-limited: fetch them immediately and do not cache.","tags":["youtube"],"operationId":"get_youtube_video_files","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video.","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type — this is a passthrough list, not a canonical object.","items":{"type":"object","description":"A single media file with a direct `url` and type-specific metadata.","properties":{"url":{"type":"string","description":"Direct URL to the media file. Audio/video stream URLs are time-limited — fetch immediately and do not cache."}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video/subtitles":{"get":{"summary":"Get a YouTube video's subtitle files","description":"Returns the downloadable subtitle/caption track files for a YouTube video — each with a language code and name, format, and a direct download `url`. Includes both manual and auto-generated tracks across available subtitle formats (srt, vtt, ttml, …).","tags":["youtube"],"operationId":"get_youtube_video_subtitles","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video.","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},{"name":"format","in":"query","required":false,"description":"Subtitle file format filter (e.g. srt, vtt, ttml, json3, srv1).","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type — this is a passthrough list, not a canonical object.","items":{"type":"object","description":"A single media file with a direct `url` and type-specific metadata.","properties":{"url":{"type":"string","description":"Direct URL to the media file. Audio/video stream URLs are time-limited — fetch immediately and do not cache."}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/youtube/video/thumbnails":{"get":{"summary":"Get a YouTube video's thumbnail files","description":"Returns the thumbnail image files for a YouTube video at every available size — each with a direct image `url`, dimensions (`width`/`height`), aspect `ratio`, and image `format` (webp / jpg).","tags":["youtube"],"operationId":"get_youtube_video_thumbnails","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the YouTube video.","schema":{"type":"string"},"example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of media-file objects for the video (audio/video streams, subtitle tracks, or thumbnails). Each item carries the file's direct `url` plus its native technical metadata (e.g. mimeType, bitrate, quality, width/height, language). The exact fields vary by file type — this is a passthrough list, not a canonical object.","items":{"type":"object","description":"A single media file with a direct `url` and type-specific metadata.","properties":{"url":{"type":"string","description":"Direct URL to the media file. Audio/video stream URLs are time-limited — fetch immediately and do not cache."}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitter/community":{"get":{"summary":"Get Twitter community details","description":"Returns information about a Twitter/X community including name, description, member count, rules, and creation date.","tags":["twitter"],"operationId":"get_twitter_community","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Twitter/X community","schema":{"type":"string"},"example":"https://x.com/i/communities/1926186499399139650"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitter/community/tweets":{"get":{"summary":"List Twitter community tweets","description":"Returns recent tweets posted in a Twitter/X community. Each tweet includes text, engagement metrics, and author info.","tags":["twitter"],"operationId":"get_twitter_community_tweets","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Twitter/X community","schema":{"type":"string"},"example":"https://x.com/i/communities/1234567890"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitter/tweet/transcript":{"get":{"summary":"Get Twitter video transcript","description":"Returns the transcript of a video attached to a tweet. Supports auto-generated captions.","tags":["twitter"],"operationId":"get_twitter_tweet_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the tweet containing a video","schema":{"type":"string"},"example":"https://x.com/TheoVon/status/1916982720317821050"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/twitter/ai-search":{"get":{"summary":"AI-powered X (Twitter) search via xAI Grok","description":"Natural-language search over X (Twitter) powered by xAI's Grok 4.3 model with the built-in x_search tool. Returns a synthesised answer plus X source citations. Pin results to specific authors via from_handles (or exclude with exclude_handles), and narrow to a time window with from_date / to_date. Costs 5 credits per call regardless of how many internal x_search invocations the model performs (see tool_calls_count in the response for visibility). Auto-refunds on upstream failure. Best for freeform questions like 'what is @elonmusk saying about xAI this week' that would otherwise require multiple structured calls to /v1/twitter/profile, /v1/twitter/user/tweets, etc.","tags":["twitter"],"operationId":"get_twitter_ai_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Natural-language prompt describing what you want to learn from X. The model autonomously searches X using the x_search tool with any handle / date filters you provide.","schema":{"type":"string"},"example":"What is @elonmusk saying about xAI this week?"},{"name":"from_handles","in":"query","required":false,"description":"Comma-separated X handles (max 10). Restricts the search to posts from these accounts only. Mutually exclusive with exclude_handles.","schema":{"type":"string"}},{"name":"exclude_handles","in":"query","required":false,"description":"Comma-separated X handles (max 10) to exclude from search results. Mutually exclusive with from_handles.","schema":{"type":"string"}},{"name":"from_date","in":"query","required":false,"description":"ISO 8601 start date (YYYY-MM-DD). Limits the search window to posts on or after this date.","schema":{"type":"string"}},{"name":"to_date","in":"query","required":false,"description":"ISO 8601 end date (YYYY-MM-DD). Limits the search window to posts on or before this date.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"twitter","endpoint":"/v1/twitter/ai-search","data":{"answer":"Elon Musk recently posted about xAI's new reasoning model, highlighting its real-time X search capability...","sources":[{"url":"https://x.com/elonmusk/status/1234567890","title":"elonmusk on X"}],"tool_calls_count":1},"credits_used":5,"credits_remaining":95,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/perplexity/research":{"get":{"summary":"Web research via Perplexity Sonar","description":"Natural-language research over the live web powered by Perplexity Sonar. Returns a synthesised answer plus the URLs Sonar cited as evidence under `data.sources`. Costs 1 credit per call. Auto-refunds on upstream failure. Best for freeform questions like 'what is the latest funding round for Anthropic' or 'summarise this week's biggest LLM releases' that need fresh, web-grounded answers — the kind of question a structured social-media call cannot answer.","tags":["perplexity"],"operationId":"get_perplexity_research","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Natural-language research prompt. Sonar autonomously searches the live web and grounds the response in real sources. No prompt-engineering required — phrase it as you would to a search engine or research assistant.","schema":{"type":"string"},"example":"What is the capital of France?"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"perplexity","endpoint":"/v1/perplexity/research","data":{"answer":"Paris is the capital of France.","sources":[{"url":"https://en.wikipedia.org/wiki/Paris","title":"Paris - Wikipedia"}]},"credits_used":1,"credits_remaining":99,"request_id":"req-a1b2c3d4e5f6","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/company/posts":{"get":{"summary":"List LinkedIn company posts","description":"Returns recent posts from a LinkedIn company page. Each post includes text, reaction count, comment count, and media.","tags":["linkedin"],"operationId":"get_linkedin_company_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"company_id","in":"query","required":true,"description":"LinkedIn numeric company ID (from /v1/linkedin/company).","schema":{"type":"string"},"example":"1035"},{"name":"page","in":"query","required":false,"description":"Page number for pagination (default 1).","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"Post ordering: 'top' or 'recent'.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/ad":{"get":{"summary":"Get LinkedIn ad details","description":"Returns detailed information about a specific LinkedIn advertisement including ad copy, sponsor info, impressions, and targeting.","tags":["linkedin","linkedin-ads"],"operationId":"get_linkedin_ad","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn ad","schema":{"type":"string"},"example":"https://www.linkedin.com/ad-library/detail/666281156"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/ads/search":{"get":{"summary":"Search LinkedIn ads","description":"Searches the LinkedIn Ad Library for ads by company, keyword, or filters. Returns matching ads with ad copy and sponsor info.","tags":["linkedin","linkedin-ads"],"operationId":"get_linkedin_ads_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"company","in":"query","required":false,"description":"The company name to search for. 'Microsoft' for example","schema":{"type":"string"},"example":"microsoft"},{"name":"keyword","in":"query","required":false,"description":"The keyword to search for","schema":{"type":"string"}},{"name":"companyId","in":"query","required":false,"description":"The company id to search for","schema":{"type":"string"}},{"name":"countries","in":"query","required":false,"description":"Comma separated list of countries. Example: US,CA,MX","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"Start date to search for. Format: YYYY-MM-DD","schema":{"type":"string"}},{"name":"endDate","in":"query","required":false,"description":"End date to search for. Format: YYYY-MM-DD","schema":{"type":"string"}},{"name":"paginationToken","in":"query","required":false,"description":"Pagination token to paginate through results","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/search/posts":{"get":{"summary":"Search public LinkedIn posts by keyword","description":"Finds public LinkedIn posts, feed updates, and Pulse articles via Google Search. Returns description, author, media, like count, comment count, and published date when LinkedIn exposes them publicly. Best-effort against Google's index, not a complete native LinkedIn search. Use `date_posted` to narrow to recent posts and forward `cursor` for pagination.","tags":["linkedin"],"operationId":"get_linkedin_search_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Keyword or phrase to search for in public LinkedIn posts.","schema":{"type":"string"},"example":"ai agents"},{"name":"page","in":"query","required":false,"description":"page","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"sort_by","schema":{"type":"string"}},{"name":"date_posted","in":"query","required":false,"description":"Date filter based on Google-indexed results.","schema":{"type":"string"}},{"name":"content_type","in":"query","required":false,"description":"content_type","schema":{"type":"string"}},{"name":"from_company","in":"query","required":false,"description":"from_company","schema":{"type":"string"}},{"name":"from_member","in":"query","required":false,"description":"from_member","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkedin/post/transcript":{"get":{"summary":"Get a LinkedIn post video transcript","description":"Fetches the transcript from a LinkedIn post video when LinkedIn exposes one publicly. Returns `transcript: null` with `transcriptNotAvailable: true` if the post has no transcript — credits are only deducted when a transcript is actually returned.","tags":["linkedin"],"operationId":"get_linkedin_post_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the LinkedIn post to transcribe.","schema":{"type":"string"},"example":"https://www.linkedin.com/posts/gemini-35-flash-is-a-step-forward-for-google-ugcPost-7465082215316525056-MHBd/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/group/posts":{"get":{"summary":"List Facebook group posts","description":"Returns recent posts from a Facebook group. Each post includes text, reaction count, comment count, shares, and author info. Pagination is not currently supported on this endpoint — the upstream returns a single page only.","tags":["facebook"],"operationId":"get_facebook_group_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["url","group_id"]],"parameters":[{"name":"url","in":"query","required":false,"description":"Full URL of the Facebook group (one of: url, group_id — at least one required)","schema":{"type":"string"}},{"name":"group_id","in":"query","required":false,"description":"The ID of the group (one of: url, group_id — at least one required)","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"How to sort the posts","schema":{"type":"string","enum":["TOP_POSTS","RECENT_ACTIVITY","CHRONOLOGICAL","CHRONOLOGICAL_LISTINGS"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/post/transcript":{"get":{"summary":"Get Facebook video transcript","description":"Returns the transcript of a Facebook video post. Supports auto-generated captions.","tags":["facebook"],"operationId":"get_facebook_post_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Facebook video post","schema":{"type":"string"},"example":"https://www.facebook.com/Meta/videos/a-slightly-life-changing-story/1459847961114516/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/profile/photos":{"get":{"summary":"List Facebook profile photos","description":"Returns Facebook page or profile photos as unified Post items. Each item includes a photo ID, permalink, full-size image URL, thumbnail, and accessibility caption when available. Per-item author, engagement counts, and publish time are not exposed, so those canonical fields and engagement counts remain null.","tags":["facebook"],"operationId":"get_facebook_profile_photos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Facebook page or profile","schema":{"type":"string"},"example":"https://www.facebook.com/Meta"},{"name":"next_page_id","in":"query","required":false,"description":"To paginate through to the next page","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"To paginate through to the next page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/profile/reels":{"get":{"summary":"List Facebook profile reels","description":"Returns Facebook page or profile reels as unified Post items. Each item includes a reel ID, description, thumbnail, duration when available, author identity, `engagement.views` when the upstream provides it, permalink, and publish time. Likes, comments, shares, and saves remain null because this endpoint does not expose those counts.","tags":["facebook"],"operationId":"get_facebook_profile_reels","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Facebook page or profile","schema":{"type":"string"},"example":"https://www.facebook.com/Meta"},{"name":"next_page_id","in":"query","required":false,"description":"To paginate through to the next page","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"To paginate through to the next page","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/adlibrary/ad":{"get":{"summary":"Get Facebook Ad Library ad details","description":"Returns detailed information about a specific ad from the Facebook Ad Library — creative, spend, impressions, and targeting. For ad video transcripts, use `/v1/facebook/adlibrary/ad/transcript` (separate endpoint, premium tier).","tags":["facebook","facebook-ads"],"operationId":"get_facebook_adlibrary_ad","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Facebook Ad Library ad ID (one of: id, url — at least one required)","schema":{"type":"string"},"example":"924576560616746"},{"name":"url","in":"query","required":false,"description":"Facebook Ad URL (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/adlibrary/company/ads":{"get":{"summary":"List Facebook Ad Library company ads","description":"Returns ads from a specific company/page in the Facebook Ad Library. Each ad includes creative, status, spend, and targeting info.","tags":["facebook","facebook-ads"],"operationId":"get_facebook_adlibrary_company_ads","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["pageId","companyName"]],"parameters":[{"name":"pageId","in":"query","required":false,"description":"Facebook page ID of the advertiser (one of: pageId, companyName — at least one required)","schema":{"type":"string"}},{"name":"companyName","in":"query","required":false,"description":"The name of the company. Can either use this or pageId (one of: pageId, companyName — at least one required)","schema":{"type":"string"},"example":"Lululemon"},{"name":"country","in":"query","required":false,"description":"This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Status of the ad. Defaults to ACTIVE.","schema":{"type":"string","enum":["ALL","ACTIVE","INACTIVE"]}},{"name":"media_type","in":"query","required":false,"description":"Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.","schema":{"type":"string","enum":["ALL","IMAGE","VIDEO","MEME","IMAGE_AND_MEME","NONE"]}},{"name":"language","in":"query","required":false,"description":"Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.","schema":{"type":"string","enum":["total_impressions","relevancy_monthly_grouped"]}},{"name":"start_date","in":"query","required":false,"description":"Start date to search for. Format: YYYY-MM-DD","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"End date to search for. Format: YYYY-MM-DD","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor to paginate through results","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/adlibrary/search/ads":{"get":{"summary":"Search Facebook Ad Library","description":"Searches the Facebook Ad Library for ads matching a keyword. Returns matching ads with creative text, images, sponsor info, and status.","tags":["facebook","facebook-ads"],"operationId":"get_facebook_adlibrary_search_ads","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find ads in the Facebook Ad Library","schema":{"type":"string"},"example":"artificial intelligence"},{"name":"sort_by","in":"query","required":false,"description":"Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.","schema":{"type":"string","enum":["total_impressions","relevancy_monthly_grouped"]}},{"name":"search_type","in":"query","required":false,"description":"If you want to search by exact phrase or not","schema":{"type":"string","enum":["keyword_unordered","keyword_exact_phrase"]}},{"name":"ad_type","in":"query","required":false,"description":"Search for all ads or only political and issue ads","schema":{"type":"string","enum":["all","political_and_issue_ads"]}},{"name":"country","in":"query","required":false,"description":"This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Status of the ad. Defaults to ACTIVE.","schema":{"type":"string","enum":["ALL","ACTIVE","INACTIVE"]}},{"name":"media_type","in":"query","required":false,"description":"Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.","schema":{"type":"string","enum":["ALL","IMAGE","VIDEO","MEME","IMAGE_AND_MEME","NONE"]}},{"name":"start_date","in":"query","required":false,"description":"Impressions start date. Needs to be in YYYY-MM-DD format.","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"Impressions end date. Needs to be in YYYY-MM-DD format.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor to paginate through results","schema":{"type":"string"}},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/adlibrary/search/companies":{"get":{"summary":"Search Facebook Ad Library companies","description":"Searches for companies/pages in the Facebook Ad Library. Returns matching pages with active ad counts and page details.","tags":["facebook","facebook-ads"],"operationId":"get_facebook_adlibrary_search_companies","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find companies in the Facebook Ad Library","schema":{"type":"string"},"example":"Nike"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/profile/events":{"get":{"summary":"List a Facebook page's events","description":"Returns upcoming and past events for a public Facebook page, including title, date/time, location, cover image, and attendee counts when exposed. Forward the returned cursor for additional pages.","tags":["facebook"],"operationId":"get_facebook_profile_events","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the public Facebook page.","schema":{"type":"string"},"example":"https://www.facebook.com/brickyardoldtown"},{"name":"cursor","in":"query","required":false,"description":"Cursor returned by the previous response for pagination.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/post/comment/replies":{"get":{"summary":"List replies to a Facebook post comment","description":"Returns the reply thread for a single Facebook comment. Both `feedback_id` and `expansion_token` come from the parent `/v1/facebook/post/comments` response — note that `feedback_id` is NOT the comment ID. Forward the returned cursor for additional pages.","tags":["facebook"],"operationId":"get_facebook_post_comment_replies","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"feedback_id","in":"query","required":true,"description":"`feedback_id` from `/v1/facebook/post/comments` for the parent comment (this is NOT the comment ID).","schema":{"type":"string"},"example":"ZmVlZGJhY2s6MzM3MzYxMzI5OTQ4Nzc1NV8xOTI5NTk0OTE3Njg3MTcz"},{"name":"expansion_token","in":"query","required":true,"description":"`expansion_token` from `/v1/facebook/post/comments` for the parent comment.","schema":{"type":"string"},"example":"MjoxNzc4NjM1MDM3OgF_JaMa3kMP9RIWC"},{"name":"cursor","in":"query","required":false,"description":"Cursor returned by the previous response for pagination.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/marketplace/location/search":{"get":{"summary":"Search Facebook Marketplace locations","description":"Searches Facebook Marketplace locations and cities, returning lat/lng coordinates you can feed into `/v1/facebook/marketplace/search`.","tags":["facebook"],"operationId":"get_facebook_marketplace_location_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Location search query (city or area name).","schema":{"type":"string"},"example":"Los Angeles"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/marketplace/search":{"get":{"summary":"Search Facebook Marketplace listings","description":"Searches Facebook Marketplace listings by keyword + lat/lng with price, condition, delivery, and date-listed filters. Forward the returned cursor for additional pages. With `sort_by=creation_time_descend`, FB may return slightly different ordering across identical requests — for alerting workflows, scrape multiple pages and dedupe by listing id rather than assuming stable order.","tags":["facebook"],"operationId":"get_facebook_marketplace_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword (e.g., `bike`, `couch`).","schema":{"type":"string"},"example":"bike"},{"name":"lat","in":"query","required":true,"description":"Latitude of the search location.","schema":{"type":"string"},"example":"40.7128"},{"name":"lng","in":"query","required":true,"description":"Longitude of the search location.","schema":{"type":"string"},"example":"-74.0060"},{"name":"radius_km","in":"query","required":false,"description":"Search radius in kilometers.","schema":{"type":"integer"}},{"name":"min_price","in":"query","required":false,"description":"Minimum listing price.","schema":{"type":"integer"}},{"name":"max_price","in":"query","required":false,"description":"Maximum listing price.","schema":{"type":"integer"}},{"name":"count","in":"query","required":false,"description":"Number of listings to return per page.","schema":{"type":"integer"}},{"name":"sort_by","in":"query","required":false,"description":"Sort order for results.","schema":{"type":"string","enum":["suggested","distance_ascend","creation_time_descend","price_ascend","price_descend"]}},{"name":"delivery_method","in":"query","required":false,"description":"Delivery filter — local pickup only, shipping only, or all.","schema":{"type":"string","enum":["all","local_pickup","shipping"]}},{"name":"condition","in":"query","required":false,"description":"Filter listings by item condition.","schema":{"type":"string","enum":["new","used_like_new","used_good","used_fair"]}},{"name":"date_listed","in":"query","required":false,"description":"Filter by listing recency (relative window or numeric day count).","schema":{"type":"string","enum":["all","1","7","30","last_24_hours","last_7_days","last_30_days"]}},{"name":"availability","in":"query","required":false,"description":"Filter by listing status — `available`, `sold`, or `all`.","schema":{"type":"string","enum":["available","sold","all"]}},{"name":"cursor","in":"query","required":false,"description":"Opaque pagination cursor returned by the previous response — forward as-is.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/marketplace/item":{"get":{"summary":"Get a Facebook Marketplace item","description":"Fetches a single Facebook Marketplace listing — title, description, price, location, condition, photos, seller, and availability flags. Pass either the numeric `id` or a full Marketplace `url`.","tags":["facebook"],"operationId":"get_facebook_marketplace_item","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Facebook Marketplace item ID (numeric). (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"Full URL of the Marketplace item. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://www.facebook.com/marketplace/item/1656586118821988/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/events/search":{"get":{"summary":"Search Facebook events by keyword","description":"Searches the public Facebook Events directory for events matching a keyword. Forward the returned cursor for additional pages.","tags":["facebook"],"operationId":"get_facebook_events_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Event name or keyword to search for.","schema":{"type":"string"},"example":"dogs"},{"name":"cursor","in":"query","required":false,"description":"Cursor returned by the previous response for pagination.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/events":{"get":{"summary":"List Facebook events for a city","description":"Returns the events listed under a Facebook city/region Events explore page. Filter by relative `time` (defaults to all time) and forward the returned cursor for additional pages.","tags":["facebook"],"operationId":"get_facebook_events","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the city's Facebook Events page.","schema":{"type":"string"},"example":"https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547"},{"name":"time","in":"query","required":false,"description":"Relative time window. Defaults to all time when omitted.","schema":{"type":"string","enum":["today","this_week","next_week"]}},{"name":"cursor","in":"query","required":false,"description":"Cursor returned by the previous response for pagination.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/event/details":{"get":{"summary":"Get details for a Facebook event","description":"Fetches full metadata for a Facebook event — title, description, start/end time, location, host, cover image, and RSVP counts when exposed.","tags":["facebook"],"operationId":"get_facebook_event_details","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Facebook event ID (numeric). (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"Full URL of the event. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://www.facebook.com/events/2255360061870188/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/facebook/adlibrary/ad/transcript":{"get":{"summary":"Get a Facebook Ad Library video ad transcript","description":"Retrieves a transcript for a single Facebook Ad Library video ad. Uses Facebook-provided captions when available, otherwise transcribes the public video URL on demand. Ads without retrievable captions return a 404 RESOURCE_NOT_FOUND, and on-demand transcription can fail transiently (503) — both outcomes are free; credits are only deducted when a transcript is returned.","tags":["facebook","facebook-ads"],"operationId":"get_facebook_adlibrary_ad_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Facebook Ad Library ad ID. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"924576560616746"},{"name":"url","in":"query","required":false,"description":"Facebook Ad Library ad URL. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://www.facebook.com/ads/library?id=924576560616746"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/reddit/subreddit/search":{"get":{"summary":"Search within a subreddit","description":"Searches for posts within a specific subreddit. Returns matching posts with titles, scores, comment counts, and permalinks.","tags":["reddit"],"operationId":"get_reddit_subreddit_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"subreddit","in":"query","required":true,"description":"Subreddit name (e.g. 'Fitness', not 'r/Fitness' or a full URL)","schema":{"type":"string"},"example":"technology"},{"name":"query","in":"query","required":false,"description":"Search query to find matching content","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort order. For posts/media: relevance, hot, top, new, comments. For comments: relevance, top, new","schema":{"type":"string","enum":["relevance","hot","top","new","comments"]}},{"name":"timeframe","in":"query","required":false,"description":"Timeframe to filter results","schema":{"type":"string","enum":["all","year","month","week","day","hour"]}},{"name":"cursor","in":"query","required":false,"description":"Cursor to get more results. Get 'cursor' from previous response.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/reddit/post/transcript":{"get":{"summary":"Get a Reddit video post transcript","description":"Returns the transcript for a Reddit video post or direct `v.redd.it` URL when Reddit exposes a VTT caption file. Includes raw WebVTT in `raw_vtt` plus a parsed plain-text transcript. When Reddit doesn't expose captions, `transcript` is `null` and `transcriptNotAvailable` is `true` — credits are only deducted when a transcript is returned.","tags":["reddit"],"operationId":"get_reddit_post_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Reddit post URL or direct v.redd.it video URL.","schema":{"type":"string"},"example":"https://www.reddit.com/r/youseeingthisshit/comments/1oiu9xm/football_nostalgiasaints_punter_head_coach_cant/"},{"name":"language","in":"query","required":false,"description":"2-letter language code. Defaults to `en`.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/threads/search/users":{"get":{"summary":"Search Threads users","description":"Searches Threads for user accounts matching a query. Returns matching profiles with follower counts and verification status.","tags":["threads"],"operationId":"get_threads_search_users","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find Threads users","schema":{"type":"string"},"example":"tech"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/pinterest/url-stats":{"get":{"summary":"Get Pinterest save counts for external URLs","description":"Returns how many times each URL (up to 10 per request, comma-separated) has been saved to Pinterest via the Save Button. Counts are exact-URL-string keyed: scheme, trailing slash, and query string each produce a different count — URLs are passed through verbatim, never normalized. A count of 0 can mean either 'never pinned' or 'page does not exist'. Counts come from the Pinterest Save Button embed ecosystem; pages outside it may undercount. Single page only — no pagination.","tags":["pinterest"],"operationId":"get_pinterest_url_stats","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"urls","in":"query","required":true,"description":"Comma-separated list of 1–10 absolute http(s):// URLs, passed to Pinterest verbatim. Variants (https vs http, with/without trailing slash, with/without query string) are counted as different URLs.","schema":{"type":"string"},"example":"https://www.allrecipes.com/recipe/10813/best-chocolate-chip-cookies/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/pinterest/board":{"get":{"summary":"Get Pinterest board","description":"Returns pins from a Pinterest board. Each pin includes title, image URL, save count, and link destination. Pagination is not currently supported on this endpoint — the upstream returns a single page only.","tags":["pinterest"],"operationId":"get_pinterest_board","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Pinterest board","schema":{"type":"string"},"example":"https://www.pinterest.com/lizmrodgers/moms-night/"},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/pinterest/user/boards":{"get":{"summary":"List Pinterest user boards","description":"Returns boards created by a Pinterest user. Each board includes title, description, pin count, and cover image.","tags":["pinterest"],"operationId":"get_pinterest_user_boards","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"The username of the user to get boards for. (e.g. broadstbullycom from https://www.pinterest.com/broadstbullycom/)","schema":{"type":"string"},"example":"pinterest"},{"name":"trim","in":"query","required":false,"description":"Set to true for a trimmed down version of the response","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/search":{"get":{"summary":"Google web search","description":"Returns Google search results for a query. Each result includes title, URL, snippet, and position.","tags":["google"],"operationId":"get_google_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase","schema":{"type":"string"},"example":"best restaurants in London"},{"name":"region","in":"query","required":false,"description":"2 letter country code, ie US, UK, CA, etc This will show results from that country","schema":{"type":"string"}},{"name":"date_posted","in":"query","required":false,"description":"Date posted","schema":{"type":"string","enum":["last-hour","last-day","last-week","last-month","last-year"]}},{"name":"page","in":"query","required":false,"description":"Page number to retrieve","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/ad":{"get":{"summary":"Get Google ad details","description":"Returns detailed information about a specific Google advertisement including ad copy, advertiser, and format.","tags":["google","google-ads"],"operationId":"get_google_ad","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"Ads Transparency Center CREATIVE URL — must include both the advertiser and creative segments (`…/advertiser/{AR…}/creative/{CR…}`). Get one from `/v1/google/company/ads`.","schema":{"type":"string"},"example":"https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10449491775734153217"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/adlibrary/advertisers/search":{"get":{"summary":"Search Google Ad Library advertisers","description":"Searches the Google Ads Transparency Center for advertisers matching a query. Returns matching advertisers with `name`, `advertiser_id`, and `region`, plus their website domains. Defaults to US when `region` is omitted — pass a 2-letter country code (e.g. `AU`, `CA`) to search advertisers in another region.","tags":["google","google-ads"],"operationId":"get_google_adlibrary_advertisers_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase to find advertisers in the Google Ads Transparency Center.","schema":{"type":"string"},"example":"lululemon"},{"name":"region","in":"query","required":false,"description":"2-letter country code to search in. Defaults to US.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/company/ads":{"get":{"summary":"List Google ads by company","description":"Returns ads from a specific company/domain in the Google Ads Transparency Center. Each ad includes creative, format, and date range.","tags":["google","google-ads"],"operationId":"get_google_company_ads","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["domain","advertiser_id"]],"parameters":[{"name":"domain","in":"query","required":false,"description":"Company domain name to look up ads for (one of: domain, advertiser_id — at least one required)","schema":{"type":"string"},"example":"lululemon.com"},{"name":"advertiser_id","in":"query","required":false,"description":"The advertiser id of the company (one of: domain, advertiser_id — at least one required)","schema":{"type":"string"}},{"name":"topic","in":"query","required":false,"description":"The topic to search for. If you search for 'political', you will also need to pass a 'region', like 'US' or 'AU'","schema":{"type":"string","enum":["all","political"]}},{"name":"region","in":"query","required":false,"description":"The region to search for. Defaults to anywhere","schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"description":"Start date to search for. Format: YYYY-MM-DD","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"End date to search for. Format: YYYY-MM-DD","schema":{"type":"string"}},{"name":"platform","in":"query","required":false,"description":"Google surface to filter ads by (e.g. youtube, google_search)","schema":{"type":"string","enum":["google_maps","google_play","google_search","google_shopping","youtube"]}},{"name":"format","in":"query","required":false,"description":"Ad format to filter by: text, image, or video","schema":{"type":"string","enum":["text","image","video"]}},{"name":"get_ad_details","in":"query","required":false,"description":"Set to true to get the ad details. Will cost 25 credits.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor to paginate through results","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/business/info":{"get":{"summary":"Get a Google Business Profile","description":"Returns the full Google Business Profile (Maps / Knowledge Panel) for a local business — name, category, rating, address, phone, coordinates, hours, attributes, and claimed status. Identify the place by keyword, cid, or place_id (cid/place_id are most reliable). Powered by DataForSEO.","tags":["google"],"operationId":"get_google_business_info","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["keyword","cid","place_id"]],"parameters":[{"name":"keyword","in":"query","required":false,"description":"Business name + address (e.g. 'Irving Farm New York 645 5th Ave'). Use cid/place_id when known for an exact match. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"},"example":"Irving Farm New York 645 5th Ave"},{"name":"cid","in":"query","required":false,"description":"Google customer id (cid) of the place — the most reliable identifier. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"}},{"name":"place_id","in":"query","required":false,"description":"Google place_id of the place. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"}},{"name":"location_name","in":"query","required":false,"description":"Geographic context as 'City,Region,Country' (default 'New York,New York,United States').","schema":{"type":"string"}},{"name":"language_name","in":"query","required":false,"description":"Result language (default 'English').","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Place ID (Google cid for a business, hotel_identifier for a hotel)"},"name":{"type":["string","null"],"description":"Business / hotel name"},"url":{"type":["string","null"],"description":"Website or canonical URL"},"category":{"type":["string","null"],"description":"Primary category (e.g. \"Coffee shop\", \"Hotel\")"},"rating":{"type":"object","description":"Aggregate rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at place.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at place.rating.max"}}},"reviews_count":{"type":["integer","null"],"description":"Number of ratings"},"price_level":{"type":["string","null"],"description":"Price band (\"inexpensive\" / \"$$\" / null)"},"address":{"type":["string","null"],"description":"String at place.address"},"phone":{"type":["string","null"],"description":"String at place.phone"},"latitude":{"type":["integer","null"],"description":"Numeric at place.latitude"},"longitude":{"type":["integer","null"],"description":"Numeric at place.longitude"},"verified":{"type":["boolean","null"],"description":"Claimed-business flag (Google is_claimed)"},"description":{"type":["string","null"],"description":"String at place.description"},"image_urls":{"type":["string","array","null"],"description":"Union: string | array | null","items":{"type":"string","description":"String at place.image_urls"}},"categories":{"type":["array","null"],"description":"Array at place.categories","items":{"type":"string","description":"String at place.categories"}},"hotel":{"type":["object","null"],"description":"Hotel-only richness (stars, amenities, review topics, prices); null for plain places","properties":{"stars":{"type":["integer","null"],"description":"Numeric at place.hotel.stars"},"stars_description":{"type":["string","null"],"description":"String at place.hotel.stars_description"},"check_in_time":{"type":["string","null"],"description":"String at place.hotel.check_in_time"},"check_out_time":{"type":["string","null"],"description":"String at place.hotel.check_out_time"},"amenities":{"type":["array","null"],"description":"Array at place.hotel.amenities","items":{"type":"object","description":"Nested object: place.hotel.amenities","properties":{"category":{"type":["string","null"],"description":"String at place.hotel.amenities.category"},"name":{"type":["string","null"],"description":"String at place.hotel.amenities.name"},"available":{"type":["boolean","null"],"description":"Boolean at place.hotel.amenities.available"},"hint":{"type":["string","null"],"description":"String at place.hotel.amenities.hint"}}}},"review_topics":{"type":["array","null"],"description":"Array at place.hotel.review_topics","items":{"type":"object","description":"Nested object: place.hotel.review_topics","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.review_topics.title"},"positive_score":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_score"},"positive_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_count"},"negative_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.negative_count"},"total_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.total_count"}}}},"prices":{"type":["array","null"],"description":"Array at place.hotel.prices","items":{"type":"object","description":"Nested object: place.hotel.prices","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.prices.title"},"price":{"type":["integer","null"],"description":"Numeric at place.hotel.prices.price"},"currency":{"type":["string","null"],"description":"String at place.hotel.prices.currency"},"url":{"type":["string","null"],"description":"String at place.hotel.prices.url"},"official_site":{"type":["boolean","null"],"description":"Boolean at place.hotel.prices.official_site"}}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/business/extended-reviews":{"get":{"summary":"Get Google extended (multi-source) reviews","description":"Returns reviews of a place aggregated from the Google reviews element — not only Google users but reputable third-party sources (TripAdvisor, Yelp, Trustpilot). Each review carries its source domain, full text (with original-language translation), star rating, reviewer stats, and owner replies. Identify the place by keyword, cid, or place_id. Powered by DataForSEO.","tags":["google"],"operationId":"get_google_business_extended_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["keyword","cid","place_id"]],"parameters":[{"name":"keyword","in":"query","required":false,"description":"Business name + address. Use cid/place_id for an exact match. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"},"example":"Irving Farm New York 645 5th Ave"},{"name":"cid","in":"query","required":false,"description":"Google customer id (cid) of the place. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"}},{"name":"place_id","in":"query","required":false,"description":"Google place_id of the place. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"}},{"name":"location_name","in":"query","required":false,"description":"Geographic context as 'City,Region,Country'.","schema":{"type":"string"}},{"name":"language_name","in":"query","required":false,"description":"Result language (default 'English').","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of reviews to return (default 20, step 20, max 1000).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/business/updates":{"get":{"summary":"Get Google Business Profile posts (updates)","description":"Returns the owner-published posts (updates) on a Google Business Profile — text, image, publish date, and any call-to-action link. Most businesses publish none; an empty result is a valid 'no posts' answer. Identify the business by keyword or cid. Powered by DataForSEO.","tags":["google"],"operationId":"get_google_business_updates","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["keyword","cid"]],"parameters":[{"name":"keyword","in":"query","required":false,"description":"Business name + location (e.g. 'Toyota of Manhattan New York'). (one of: keyword, cid — at least one required)","schema":{"type":"string"},"example":"Toyota of Manhattan New York"},{"name":"cid","in":"query","required":false,"description":"Google customer id (cid) of the business. (one of: keyword, cid — at least one required)","schema":{"type":"string"}},{"name":"location_name","in":"query","required":false,"description":"Geographic context as 'City,Region,Country'.","schema":{"type":"string"}},{"name":"language_name","in":"query","required":false,"description":"Result language (default 'English').","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/business/questions":{"get":{"summary":"Get Google Business Profile questions & answers","description":"Returns the community Q&A on a Google Business Profile — each question and its answers flattened into one comment list linked by parent_id. Identify the business by keyword, cid, or place_id. Powered by DataForSEO.","tags":["google"],"operationId":"get_google_business_questions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"x-socialcrawl-oneOf":[["keyword","cid","place_id"]],"parameters":[{"name":"keyword","in":"query","required":false,"description":"Business name + location (e.g. 'Starbucks Reserve Roastery New York'). (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"},"example":"Starbucks Reserve Roastery New York"},{"name":"cid","in":"query","required":false,"description":"Google customer id (cid) of the business. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"}},{"name":"place_id","in":"query","required":false,"description":"Google place_id of the business. (one of: keyword, cid, place_id — at least one required)","schema":{"type":"string"}},{"name":"location_name","in":"query","required":false,"description":"Geographic context as 'City,Region,Country'.","schema":{"type":"string"}},{"name":"language_name","in":"query","required":false,"description":"Result language (default 'English').","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of questions to return (default 20).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/hotels/search":{"get":{"summary":"Search Google hotels","description":"Returns hotels for a query from Google Travel — name, star rating, review score, coordinates, images, and nightly price. Dates default to next-day / one-night / two-visitors when omitted. Each hotel_identifier can be passed to GET /v1/google/hotels/info for full detail. Powered by DataForSEO.","tags":["google"],"operationId":"get_google_hotels_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"keyword","in":"query","required":true,"description":"Hotel search query (e.g. 'hotels in New York').","schema":{"type":"string"},"example":"hotels in New York"},{"name":"location_name","in":"query","required":false,"description":"Geographic context as 'City,Region,Country'.","schema":{"type":"string"}},{"name":"language_name","in":"query","required":false,"description":"Result language (default 'English').","schema":{"type":"string"}},{"name":"check_in","in":"query","required":false,"description":"Check-in date (YYYY-MM-DD). Defaults to the next day.","schema":{"type":"string"}},{"name":"check_out","in":"query","required":false,"description":"Check-out date (YYYY-MM-DD). Defaults to one night.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical place wrappers ({ place })","items":{"type":"object","description":"Canonical place wrapper","properties":{"place":{"type":"object","description":"Canonical Place object (physical/local business or hotel)","properties":{"id":{"type":"string","description":"Place ID (Google cid for a business, hotel_identifier for a hotel)"},"name":{"type":["string","null"],"description":"Business / hotel name"},"url":{"type":["string","null"],"description":"Website or canonical URL"},"category":{"type":["string","null"],"description":"Primary category (e.g. \"Coffee shop\", \"Hotel\")"},"rating":{"type":"object","description":"Aggregate rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at place.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at place.rating.max"}}},"reviews_count":{"type":["integer","null"],"description":"Number of ratings"},"price_level":{"type":["string","null"],"description":"Price band (\"inexpensive\" / \"$$\" / null)"},"address":{"type":["string","null"],"description":"String at place.address"},"phone":{"type":["string","null"],"description":"String at place.phone"},"latitude":{"type":["integer","null"],"description":"Numeric at place.latitude"},"longitude":{"type":["integer","null"],"description":"Numeric at place.longitude"},"verified":{"type":["boolean","null"],"description":"Claimed-business flag (Google is_claimed)"},"description":{"type":["string","null"],"description":"String at place.description"},"image_urls":{"type":["string","array","null"],"description":"Union: string | array | null","items":{"type":"string","description":"String at place.image_urls"}},"categories":{"type":["array","null"],"description":"Array at place.categories","items":{"type":"string","description":"String at place.categories"}},"hotel":{"type":["object","null"],"description":"Hotel-only richness (stars, amenities, review topics, prices); null for plain places","properties":{"stars":{"type":["integer","null"],"description":"Numeric at place.hotel.stars"},"stars_description":{"type":["string","null"],"description":"String at place.hotel.stars_description"},"check_in_time":{"type":["string","null"],"description":"String at place.hotel.check_in_time"},"check_out_time":{"type":["string","null"],"description":"String at place.hotel.check_out_time"},"amenities":{"type":["array","null"],"description":"Array at place.hotel.amenities","items":{"type":"object","description":"Nested object: place.hotel.amenities","properties":{"category":{"type":["string","null"],"description":"String at place.hotel.amenities.category"},"name":{"type":["string","null"],"description":"String at place.hotel.amenities.name"},"available":{"type":["boolean","null"],"description":"Boolean at place.hotel.amenities.available"},"hint":{"type":["string","null"],"description":"String at place.hotel.amenities.hint"}}}},"review_topics":{"type":["array","null"],"description":"Array at place.hotel.review_topics","items":{"type":"object","description":"Nested object: place.hotel.review_topics","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.review_topics.title"},"positive_score":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_score"},"positive_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_count"},"negative_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.negative_count"},"total_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.total_count"}}}},"prices":{"type":["array","null"],"description":"Array at place.hotel.prices","items":{"type":"object","description":"Nested object: place.hotel.prices","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.prices.title"},"price":{"type":["integer","null"],"description":"Numeric at place.hotel.prices.price"},"currency":{"type":["string","null"],"description":"String at place.hotel.prices.currency"},"url":{"type":["string","null"],"description":"String at place.hotel.prices.url"},"official_site":{"type":["boolean","null"],"description":"Boolean at place.hotel.prices.official_site"}}}}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google/hotels/info":{"get":{"summary":"Get Google hotel detail","description":"Returns full detail for a hotel by its hotel_identifier (from GET /v1/google/hotels/search) — description, star rating, address, phone, coordinates, amenities across 14 categories, 27 review-sentiment topics, and a multi-vendor price comparison. Powered by DataForSEO.","tags":["google"],"operationId":"get_google_hotels_info","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"hotel_identifier","in":"query","required":true,"description":"Opaque hotel id returned by GET /v1/google/hotels/search.","schema":{"type":"string"},"example":"ChkIoYjXwK-S_okHGg0vZy8xMW1fd3MzY243EAE"},{"name":"location_name","in":"query","required":false,"description":"Geographic context as 'City,Region,Country'.","schema":{"type":"string"}},{"name":"language_name","in":"query","required":false,"description":"Result language (default 'English').","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Place ID (Google cid for a business, hotel_identifier for a hotel)"},"name":{"type":["string","null"],"description":"Business / hotel name"},"url":{"type":["string","null"],"description":"Website or canonical URL"},"category":{"type":["string","null"],"description":"Primary category (e.g. \"Coffee shop\", \"Hotel\")"},"rating":{"type":"object","description":"Aggregate rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at place.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at place.rating.max"}}},"reviews_count":{"type":["integer","null"],"description":"Number of ratings"},"price_level":{"type":["string","null"],"description":"Price band (\"inexpensive\" / \"$$\" / null)"},"address":{"type":["string","null"],"description":"String at place.address"},"phone":{"type":["string","null"],"description":"String at place.phone"},"latitude":{"type":["integer","null"],"description":"Numeric at place.latitude"},"longitude":{"type":["integer","null"],"description":"Numeric at place.longitude"},"verified":{"type":["boolean","null"],"description":"Claimed-business flag (Google is_claimed)"},"description":{"type":["string","null"],"description":"String at place.description"},"image_urls":{"type":["string","array","null"],"description":"Union: string | array | null","items":{"type":"string","description":"String at place.image_urls"}},"categories":{"type":["array","null"],"description":"Array at place.categories","items":{"type":"string","description":"String at place.categories"}},"hotel":{"type":["object","null"],"description":"Hotel-only richness (stars, amenities, review topics, prices); null for plain places","properties":{"stars":{"type":["integer","null"],"description":"Numeric at place.hotel.stars"},"stars_description":{"type":["string","null"],"description":"String at place.hotel.stars_description"},"check_in_time":{"type":["string","null"],"description":"String at place.hotel.check_in_time"},"check_out_time":{"type":["string","null"],"description":"String at place.hotel.check_out_time"},"amenities":{"type":["array","null"],"description":"Array at place.hotel.amenities","items":{"type":"object","description":"Nested object: place.hotel.amenities","properties":{"category":{"type":["string","null"],"description":"String at place.hotel.amenities.category"},"name":{"type":["string","null"],"description":"String at place.hotel.amenities.name"},"available":{"type":["boolean","null"],"description":"Boolean at place.hotel.amenities.available"},"hint":{"type":["string","null"],"description":"String at place.hotel.amenities.hint"}}}},"review_topics":{"type":["array","null"],"description":"Array at place.hotel.review_topics","items":{"type":"object","description":"Nested object: place.hotel.review_topics","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.review_topics.title"},"positive_score":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_score"},"positive_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_count"},"negative_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.negative_count"},"total_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.total_count"}}}},"prices":{"type":["array","null"],"description":"Array at place.hotel.prices","items":{"type":"object","description":"Nested object: place.hotel.prices","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.prices.title"},"price":{"type":["integer","null"],"description":"Numeric at place.hotel.prices.price"},"currency":{"type":["string","null"],"description":"String at place.hotel.prices.currency"},"url":{"type":["string","null"],"description":"String at place.hotel.prices.url"},"official_site":{"type":["boolean","null"],"description":"Boolean at place.hotel.prices.official_site"}}}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/amazon/shop":{"get":{"summary":"Get Amazon shop page","description":"Returns product listings from an Amazon shop or storefront page including product names, prices, ratings, and images.","tags":["amazon"],"operationId":"get_amazon_shop","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Amazon shop or storefront page","schema":{"type":"string"},"example":"https://www.amazon.com/shop/sydneydelrey"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/amazon/product-search":{"get":{"summary":"Search Amazon products by keyword","description":"Returns organic Amazon search results for a keyword — title, price, rating, image, and ASIN per product. Powered by DataForSEO; results reflect the chosen marketplace (default United States). Sponsored placements and related searches are excluded in v1.","tags":["amazon"],"operationId":"get_amazon_product_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword or phrase.","schema":{"type":"string"},"example":"wireless earbuds"},{"name":"country","in":"query","required":false,"description":"Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace.","schema":{"type":"string","enum":["US","GB","CA","DE","FR","IT","ES","JP","IN","MX","BR","AU","NL"]},"example":"US"},{"name":"depth","in":"query","required":false,"description":"Maximum number of products to return (max 700). Higher depth returns more rows at the same flat credit cost.","schema":{"type":"integer"},"example":20},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical product wrappers ({ product })","items":{"type":"object","description":"Canonical product wrapper","properties":{"product":{"type":"object","description":"Canonical Product object (unified across commerce platforms)","properties":{"id":{"type":"string","description":"Platform product ID (Amazon ASIN / Google Shopping product id)"},"url":{"type":["string","null"],"description":"Direct URL to the product page"},"title":{"type":["string","null"],"description":"Product title"},"description":{"type":["string","null"],"description":"String at product.description"},"seller":{"type":["string","null"],"description":"String at product.seller"},"brand":{"type":["string","null"],"description":"Brand name (cleaned). Null when the platform exposes a seller instead."},"price":{"type":"object","description":"Price block (current, original/list, currency)","properties":{"current":{"type":["integer","null"],"description":"Numeric at product.price.current"},"original":{"type":["integer","null"],"description":"Numeric at product.price.original"},"currency":{"type":["string","null"],"description":"String at product.price.currency"}}},"rating":{"type":"object","description":"Aggregate rating (average + number of ratings)","properties":{"average":{"type":["integer","null"],"description":"Numeric at product.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at product.rating.count"}}},"image_urls":{"type":["string","array","null"],"description":"Primary image URL, or an array of image URLs for products with a gallery.","items":{"type":"string","description":"Primary image URL, or an array of image URLs for products with a gallery."}},"availability":{"type":["string","null"],"description":"Stock/availability string when surfaced"},"reviews_count":{"type":["integer","null"],"description":"Numeric at product.reviews_count"},"features":{"type":["array","null"],"description":"Array at product.features","items":{"type":"string","description":"String at product.features"}},"specifications":{"type":["array","null"],"description":"Array at product.specifications","items":{"type":"object","description":"Nested object: product.specifications","properties":{"group":{"type":["string","null"],"description":"String at product.specifications.group"},"name":{"type":["string","null"],"description":"String at product.specifications.name"},"value":{"type":["string","null"],"description":"String at product.specifications.value"}}}},"variations":{"type":["array","null"],"description":"Array at product.variations","items":{"type":"object","description":"Nested object: product.variations","properties":{"id":{"type":["string","null"],"description":"String at product.variations.id"},"title":{"type":["string","null"],"description":"String at product.variations.title"},"url":{"type":["string","null"],"description":"String at product.variations.url"},"category":{"type":["string","null"],"description":"String at product.variations.category"}}}},"ext":{"type":["object","null"],"description":"Nested object: product.ext","properties":{"gid":{"type":["string","null"],"description":"String at product.ext.gid"},"data_docid":{"type":["string","null"],"description":"String at product.ext.data_docid"},"pvf":{"type":["string","null"],"description":"String at product.ext.pvf"},"seller_id":{"type":["string","null"],"description":"String at product.ext.seller_id"},"sold_count":{"type":["integer","null"],"description":"Numeric at product.ext.sold_count"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/amazon/product":{"get":{"summary":"Get an Amazon product by ASIN","description":"Returns full product detail for an Amazon ASIN — title, brand, description, price, rating, image gallery, specifications, and variant ASINs. Powered by DataForSEO. For this product's customer reviews, call GET /v1/amazon/reviews with the same ASIN (shared upstream call).","tags":["amazon"],"operationId":"get_amazon_product","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"asin","in":"query","required":true,"description":"10-character Amazon ASIN (the product identifier).","schema":{"type":"string"},"example":"B0FQFB8FMG"},{"name":"country","in":"query","required":false,"description":"Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace.","schema":{"type":"string","enum":["US","GB","CA","DE","FR","IT","ES","JP","IN","MX","BR","AU","NL"]},"example":"US"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform product ID (Amazon ASIN / Google Shopping product id)"},"url":{"type":["string","null"],"description":"Direct URL to the product page"},"title":{"type":["string","null"],"description":"Product title"},"description":{"type":["string","null"],"description":"String at product.description"},"seller":{"type":["string","null"],"description":"String at product.seller"},"brand":{"type":["string","null"],"description":"Brand name (cleaned). Null when the platform exposes a seller instead."},"price":{"type":"object","description":"Price block (current, original/list, currency)","properties":{"current":{"type":["integer","null"],"description":"Numeric at product.price.current"},"original":{"type":["integer","null"],"description":"Numeric at product.price.original"},"currency":{"type":["string","null"],"description":"String at product.price.currency"}}},"rating":{"type":"object","description":"Aggregate rating (average + number of ratings)","properties":{"average":{"type":["integer","null"],"description":"Numeric at product.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at product.rating.count"}}},"image_urls":{"type":["string","array","null"],"description":"Primary image URL, or an array of image URLs for products with a gallery.","items":{"type":"string","description":"Primary image URL, or an array of image URLs for products with a gallery."}},"availability":{"type":["string","null"],"description":"Stock/availability string when surfaced"},"reviews_count":{"type":["integer","null"],"description":"Numeric at product.reviews_count"},"features":{"type":["array","null"],"description":"Array at product.features","items":{"type":"string","description":"String at product.features"}},"specifications":{"type":["array","null"],"description":"Array at product.specifications","items":{"type":"object","description":"Nested object: product.specifications","properties":{"group":{"type":["string","null"],"description":"String at product.specifications.group"},"name":{"type":["string","null"],"description":"String at product.specifications.name"},"value":{"type":["string","null"],"description":"String at product.specifications.value"}}}},"variations":{"type":["array","null"],"description":"Array at product.variations","items":{"type":"object","description":"Nested object: product.variations","properties":{"id":{"type":["string","null"],"description":"String at product.variations.id"},"title":{"type":["string","null"],"description":"String at product.variations.title"},"url":{"type":["string","null"],"description":"String at product.variations.url"},"category":{"type":["string","null"],"description":"String at product.variations.category"}}}},"ext":{"type":["object","null"],"description":"Nested object: product.ext","properties":{"gid":{"type":["string","null"],"description":"String at product.ext.gid"},"data_docid":{"type":["string","null"],"description":"String at product.ext.data_docid"},"pvf":{"type":["string","null"],"description":"String at product.ext.pvf"},"seller_id":{"type":["string","null"],"description":"String at product.ext.seller_id"},"sold_count":{"type":["integer","null"],"description":"Numeric at product.ext.sold_count"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/amazon/reviews":{"get":{"summary":"Get Amazon product reviews","description":"Returns the customer reviews shown on an Amazon product page (by ASIN) — typically around 8 per product (5–13 range). Each review carries the full text, star rating, reviewer, verified-purchase flag, helpful-vote count, and any review images. Powered by DataForSEO.","tags":["amazon"],"operationId":"get_amazon_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"asin","in":"query","required":true,"description":"10-character Amazon ASIN (the product identifier).","schema":{"type":"string"},"example":"B0DCH8VDXF"},{"name":"country","in":"query","required":false,"description":"Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace.","schema":{"type":"string","enum":["US","GB","CA","DE","FR","IT","ES","JP","IN","MX","BR","AU","NL"]},"example":"US"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/amazon/sellers":{"get":{"summary":"Get Amazon sellers and offers for a product","description":"Returns every seller offering a given Amazon ASIN — seller name, price, rating, and condition (new / used / refurbished), including the buy-box winner. Powered by DataForSEO.","tags":["amazon"],"operationId":"get_amazon_sellers","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"asin","in":"query","required":true,"description":"10-character Amazon ASIN (the product identifier).","schema":{"type":"string"},"example":"B09SM24S8C"},{"name":"country","in":"query","required":false,"description":"Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Note: non-US marketplaces (especially EU) are best-effort — the upstream provider is slower and occasionally times out for these; such calls are refunded, and US is the most reliable marketplace.","schema":{"type":"string","enum":["US","GB","CA","DE","FR","IT","ES","JP","IN","MX","BR","AU","NL"]},"example":"US"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical seller wrappers ({ seller })","items":{"type":"object","description":"Canonical seller wrapper","properties":{"seller":{"type":"object","description":"Canonical Seller/offer object (shared across commerce platforms)","properties":{"id":{"type":["string","null"],"description":"String at seller.id"},"name":{"type":["string","null"],"description":"Seller name"},"domain":{"type":["string","null"],"description":"String at seller.domain"},"url":{"type":["string","null"],"description":"String at seller.url"},"price":{"type":"object","description":"Offer price breakdown (base, tax, shipping, total, currency)","properties":{"base":{"type":["integer","null"],"description":"Numeric at seller.price.base"},"tax":{"type":["integer","null"],"description":"Numeric at seller.price.tax"},"shipping":{"type":["integer","null"],"description":"Numeric at seller.price.shipping"},"total":{"type":["integer","null"],"description":"Numeric at seller.price.total"},"currency":{"type":["string","null"],"description":"String at seller.price.currency"}}},"rating":{"type":"object","description":"Nested object: seller.rating","properties":{"average":{"type":["integer","null"],"description":"Numeric at seller.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at seller.rating.count"}}},"condition":{"type":["string","null"],"description":"Item condition (e.g. \"New\", \"Refurbished - Excellent\")"},"availability":{"type":["string","null"],"description":"String at seller.availability"},"annotation":{"type":["string","null"],"description":"String at seller.annotation"}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_shopping/product-search":{"get":{"summary":"Search Google Shopping products","description":"Searches Google Shopping for products matching a keyword. Returns a unified ProductList with title, seller, price (current/original/currency), rating, image URLs, and the opaque product identifiers (id, ext.gid, ext.data_docid) required to fetch product detail, reviews, or sellers. Sourced from DataForSEO's task-based Merchant/Google API; the async lifecycle is handled server-side, so this is an ordinary synchronous request. First calls take ~20-30s, then serve from cache.","tags":["google_shopping"],"operationId":"get_google_shopping_product_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Product search keyword (e.g. 'wireless earbuds').","schema":{"type":"string"},"example":"wireless earbuds"},{"name":"country","in":"query","required":false,"description":"DataForSEO location name (e.g. 'United States', 'United Kingdom'). Defaults to United States.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to en.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of product results to retrieve (default 40, max 120). More results = longer task time.","schema":{"type":"integer"}},{"name":"price_min","in":"query","required":false,"description":"Minimum product price filter.","schema":{"type":"string"}},{"name":"price_max","in":"query","required":false,"description":"Maximum product price filter.","schema":{"type":"string"}},{"name":"sort_by","in":"query","required":false,"description":"Result ordering: review_score, price_low_to_high, or price_high_to_low.","schema":{"type":"string","enum":["review_score","price_low_to_high","price_high_to_low"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical product wrappers ({ product })","items":{"type":"object","description":"Canonical product wrapper","properties":{"product":{"type":"object","description":"Canonical Product object (unified across commerce platforms)","properties":{"id":{"type":"string","description":"Platform product ID (Amazon ASIN / Google Shopping product id)"},"url":{"type":["string","null"],"description":"Direct URL to the product page"},"title":{"type":["string","null"],"description":"Product title"},"description":{"type":["string","null"],"description":"String at product.description"},"seller":{"type":["string","null"],"description":"String at product.seller"},"brand":{"type":["string","null"],"description":"Brand name (cleaned). Null when the platform exposes a seller instead."},"price":{"type":"object","description":"Price block (current, original/list, currency)","properties":{"current":{"type":["integer","null"],"description":"Numeric at product.price.current"},"original":{"type":["integer","null"],"description":"Numeric at product.price.original"},"currency":{"type":["string","null"],"description":"String at product.price.currency"}}},"rating":{"type":"object","description":"Aggregate rating (average + number of ratings)","properties":{"average":{"type":["integer","null"],"description":"Numeric at product.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at product.rating.count"}}},"image_urls":{"type":["string","array","null"],"description":"Primary image URL, or an array of image URLs for products with a gallery.","items":{"type":"string","description":"Primary image URL, or an array of image URLs for products with a gallery."}},"availability":{"type":["string","null"],"description":"Stock/availability string when surfaced"},"reviews_count":{"type":["integer","null"],"description":"Numeric at product.reviews_count"},"features":{"type":["array","null"],"description":"Array at product.features","items":{"type":"string","description":"String at product.features"}},"specifications":{"type":["array","null"],"description":"Array at product.specifications","items":{"type":"object","description":"Nested object: product.specifications","properties":{"group":{"type":["string","null"],"description":"String at product.specifications.group"},"name":{"type":["string","null"],"description":"String at product.specifications.name"},"value":{"type":["string","null"],"description":"String at product.specifications.value"}}}},"variations":{"type":["array","null"],"description":"Array at product.variations","items":{"type":"object","description":"Nested object: product.variations","properties":{"id":{"type":["string","null"],"description":"String at product.variations.id"},"title":{"type":["string","null"],"description":"String at product.variations.title"},"url":{"type":["string","null"],"description":"String at product.variations.url"},"category":{"type":["string","null"],"description":"String at product.variations.category"}}}},"ext":{"type":["object","null"],"description":"Nested object: product.ext","properties":{"gid":{"type":["string","null"],"description":"String at product.ext.gid"},"data_docid":{"type":["string","null"],"description":"String at product.ext.data_docid"},"pvf":{"type":["string","null"],"description":"String at product.ext.pvf"},"seller_id":{"type":["string","null"],"description":"String at product.ext.seller_id"},"sold_count":{"type":["integer","null"],"description":"Numeric at product.ext.sold_count"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_shopping/product":{"get":{"summary":"Get Google Shopping product detail","description":"Returns the full detail for a single Google Shopping product: title, description, rating, image gallery, feature bullets, specifications (grouped name/value), and product variations. Pass any one of the opaque identifiers (product_id, gid, or data_docid) returned by /v1/google_shopping/product-search — all three are recommended for accuracy.","tags":["google_shopping"],"operationId":"get_google_shopping_product","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["product_id","gid","data_docid"]],"parameters":[{"name":"product_id","in":"query","required":false,"description":"Google Shopping product_id (from product-search). (one of: product_id, gid, data_docid — at least one required)","schema":{"type":"string"},"example":"1749519698216963169"},{"name":"gid","in":"query","required":false,"description":"Google Shopping gid (from product-search). (one of: product_id, gid, data_docid — at least one required)","schema":{"type":"string"}},{"name":"data_docid","in":"query","required":false,"description":"Google Shopping data_docid (from product-search). (one of: product_id, gid, data_docid — at least one required)","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"DataForSEO location name. Defaults to United States.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code. Defaults to en.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform product ID (Amazon ASIN / Google Shopping product id)"},"url":{"type":["string","null"],"description":"Direct URL to the product page"},"title":{"type":["string","null"],"description":"Product title"},"description":{"type":["string","null"],"description":"String at product.description"},"seller":{"type":["string","null"],"description":"String at product.seller"},"brand":{"type":["string","null"],"description":"Brand name (cleaned). Null when the platform exposes a seller instead."},"price":{"type":"object","description":"Price block (current, original/list, currency)","properties":{"current":{"type":["integer","null"],"description":"Numeric at product.price.current"},"original":{"type":["integer","null"],"description":"Numeric at product.price.original"},"currency":{"type":["string","null"],"description":"String at product.price.currency"}}},"rating":{"type":"object","description":"Aggregate rating (average + number of ratings)","properties":{"average":{"type":["integer","null"],"description":"Numeric at product.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at product.rating.count"}}},"image_urls":{"type":["string","array","null"],"description":"Primary image URL, or an array of image URLs for products with a gallery.","items":{"type":"string","description":"Primary image URL, or an array of image URLs for products with a gallery."}},"availability":{"type":["string","null"],"description":"Stock/availability string when surfaced"},"reviews_count":{"type":["integer","null"],"description":"Numeric at product.reviews_count"},"features":{"type":["array","null"],"description":"Array at product.features","items":{"type":"string","description":"String at product.features"}},"specifications":{"type":["array","null"],"description":"Array at product.specifications","items":{"type":"object","description":"Nested object: product.specifications","properties":{"group":{"type":["string","null"],"description":"String at product.specifications.group"},"name":{"type":["string","null"],"description":"String at product.specifications.name"},"value":{"type":["string","null"],"description":"String at product.specifications.value"}}}},"variations":{"type":["array","null"],"description":"Array at product.variations","items":{"type":"object","description":"Nested object: product.variations","properties":{"id":{"type":["string","null"],"description":"String at product.variations.id"},"title":{"type":["string","null"],"description":"String at product.variations.title"},"url":{"type":["string","null"],"description":"String at product.variations.url"},"category":{"type":["string","null"],"description":"String at product.variations.category"}}}},"ext":{"type":["object","null"],"description":"Nested object: product.ext","properties":{"gid":{"type":["string","null"],"description":"String at product.ext.gid"},"data_docid":{"type":["string","null"],"description":"String at product.ext.data_docid"},"pvf":{"type":["string","null"],"description":"String at product.ext.pvf"},"seller_id":{"type":["string","null"],"description":"String at product.ext.seller_id"},"sold_count":{"type":["integer","null"],"description":"Numeric at product.ext.sold_count"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_shopping/reviews":{"get":{"summary":"Get Google Shopping product reviews","description":"Returns a unified ReviewList for a Google Shopping product, aggregated across retailers (each review's `source` is the hosting retailer domain). Each review carries the title, full text, star rating, author (when present), images, and publication date. Pass the product's gid (from product-search); product_id and data_docid are recommended for accuracy. Products with no Google Shopping reviews return 404 (auto-refunded).","tags":["google_shopping"],"operationId":"get_google_shopping_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"gid","in":"query","required":true,"description":"Google Shopping gid of the product (from product-search). Required.","schema":{"type":"string"},"example":"3591805395819257241"},{"name":"product_id","in":"query","required":false,"description":"Google Shopping product_id (recommended for accuracy).","schema":{"type":"string"}},{"name":"data_docid","in":"query","required":false,"description":"Google Shopping data_docid (recommended for accuracy).","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of reviews to retrieve (default 10, multiples of 10, max 8000).","schema":{"type":"integer"}},{"name":"country","in":"query","required":false,"description":"DataForSEO location name. Defaults to United States.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code. Defaults to en.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_shopping/sellers":{"get":{"summary":"Get Google Shopping sellers for a product","description":"Returns the list of sellers/offers for a single Google Shopping product: seller name, domain, itemised price (base/tax/shipping/total/currency), rating, product condition, availability, and any special-offer annotation. Pass any one of the opaque identifiers (product_id, gid, or data_docid) from product-search.","tags":["google_shopping"],"operationId":"get_google_shopping_sellers","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["product_id","gid","data_docid"]],"parameters":[{"name":"product_id","in":"query","required":false,"description":"Google Shopping product_id (from product-search). (one of: product_id, gid, data_docid — at least one required)","schema":{"type":"string"},"example":"1749519698216963169"},{"name":"gid","in":"query","required":false,"description":"Google Shopping gid (from product-search). (one of: product_id, gid, data_docid — at least one required)","schema":{"type":"string"}},{"name":"data_docid","in":"query","required":false,"description":"Google Shopping data_docid (from product-search). (one of: product_id, gid, data_docid — at least one required)","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"DataForSEO location name. Defaults to United States.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code. Defaults to en.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical seller wrappers ({ seller })","items":{"type":"object","description":"Canonical seller wrapper","properties":{"seller":{"type":"object","description":"Canonical Seller/offer object (shared across commerce platforms)","properties":{"id":{"type":["string","null"],"description":"String at seller.id"},"name":{"type":["string","null"],"description":"Seller name"},"domain":{"type":["string","null"],"description":"String at seller.domain"},"url":{"type":["string","null"],"description":"String at seller.url"},"price":{"type":"object","description":"Offer price breakdown (base, tax, shipping, total, currency)","properties":{"base":{"type":["integer","null"],"description":"Numeric at seller.price.base"},"tax":{"type":["integer","null"],"description":"Numeric at seller.price.tax"},"shipping":{"type":["integer","null"],"description":"Numeric at seller.price.shipping"},"total":{"type":["integer","null"],"description":"Numeric at seller.price.total"},"currency":{"type":["string","null"],"description":"String at seller.price.currency"}}},"rating":{"type":"object","description":"Nested object: seller.rating","properties":{"average":{"type":["integer","null"],"description":"Numeric at seller.rating.average"},"count":{"type":["integer","null"],"description":"Numeric at seller.rating.count"}}},"condition":{"type":["string","null"],"description":"Item condition (e.g. \"New\", \"Refurbished - Excellent\")"},"availability":{"type":["string","null"],"description":"String at seller.availability"},"annotation":{"type":["string","null"],"description":"String at seller.annotation"}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_news/search":{"get":{"summary":"Search Google News","description":"Returns a unified NewsArticleList of the top Google News results for a keyword, right now — headline, source outlet, snippet, thumbnail, article URL, and absolute UTC publish time. Combines Google's main news ranking and the Top Stories carousel into one list (`placement` distinguishes them). Localize with `location_name`/`location_code`/`location_coordinate` + `language_code` (non-Latin scripts supported). Filter by recency with `time_range`. There is no pagination beyond `depth` — Google News exposes at most 200 articles per query (default 10, max 100 on this surface). For the full article body, scrape the returned `url`. Sourced live from DataForSEO's Google News SERP — an ordinary synchronous request (~1-3s).","tags":["google_news"],"operationId":"get_google_news_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"keyword","in":"query","required":true,"description":"Search query (e.g. 'openai'). Supports any language; pass the matching language_code. Advanced operators (site:, intitle:, cache:, …) are not supported.","schema":{"type":"string"},"example":"openai"},{"name":"depth","in":"query","required":false,"description":"Number of articles to retrieve (default 10, multiples of 10, max 100). No pagination beyond depth.","schema":{"type":"integer"},"example":20},{"name":"location_code","in":"query","required":false,"description":"Google location code (e.g. 2840 = United States). Use one of location_code / location_name / location_coordinate.","schema":{"type":"integer"}},{"name":"location_name","in":"query","required":false,"description":"Google location name (e.g. 'South Korea').","schema":{"type":"string"}},{"name":"location_coordinate","in":"query","required":false,"description":"GPS target as 'latitude,longitude,radius_mm' (e.g. '40.7128,-74.0060,200') for local-news radius queries.","schema":{"type":"string"}},{"name":"language_code","in":"query","required":false,"description":"Google language code (e.g. 'en', 'ko'). Default 'en'.","schema":{"type":"string"},"example":"en"},{"name":"time_range","in":"query","required":false,"description":"Only return articles published within this window: hour, day, week, month, or year.","schema":{"type":"string","enum":["hour","day","week","month","year"]},"example":"day"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical news article wrappers ({ article })","items":{"type":"object","description":"Canonical news article wrapper","properties":{"article":{"type":"object","description":"Canonical NewsArticle object (unified across news sources)","properties":{"id":{"type":"string","description":"Stable article ID (hash of the url)"},"title":{"type":["string","null"],"description":"Article headline"},"url":{"type":["string","null"],"description":"Direct URL to the article"},"source":{"type":["string","null"],"description":"Publishing outlet name (falls back to the domain)"},"domain":{"type":["string","null"],"description":"Host domain of the article"},"snippet":{"type":["string","null"],"description":"Article excerpt (news_search items only; null on top_stories)"},"image_url":{"type":["string","null"],"description":"Thumbnail image URL"},"published_at":{"type":["string","integer","null"],"description":"Absolute UTC publish time"},"rank":{"type":["integer","null"],"description":"Result rank (news_search items only; null on top_stories)"},"placement":{"type":["string","null"],"description":"Source list: \"news_search\" or \"top_stories\""}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_finance/quote":{"get":{"summary":"Get a financial instrument quote","description":"Returns ONE rich, unified Quote for a financial instrument keyed by its `keyword` (`TICKER:EXCHANGE` for stocks/ETFs/indices, e.g. 'GOOGL:NASDAQ' / 'VOO:NYSEARCA' / '.INX:INDEXSP', or a forex/crypto pair, e.g. 'EUR-USD' / 'BTC-USD'). A single call bundles the live price + intraday graph, fundamentals (market cap, P/E, dividend yield, 52-week range, volumes), the company profile (CEO, founded, HQ, employees), quarterly + annual financials (equities), and peer instruments — all on ONE canonical shape across stocks, ETFs, indices, crypto, and forex, distinguished by `quote.type`. Forex/crypto pairs populate `quote.pair` (base/quote symbols) and have a null `ticker`. Get the exact `keyword` from /v1/google_finance/ticker-search. Sourced live from DataForSEO's Google Finance SERP (~5-10s).","tags":["google_finance"],"operationId":"get_google_finance_quote","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"keyword","in":"query","required":true,"description":"Instrument identifier: TICKER:EXCHANGE for stocks/ETFs/indices ('GOOGL:NASDAQ', '.INX:INDEXSP') or a forex/crypto pair ('EUR-USD', 'BTC-USD'). Use the `id` returned by ticker-search.","schema":{"type":"string"},"example":"GOOGL:NASDAQ"},{"name":"language","in":"query","required":false,"description":"Language as a DFS name ('English') or 2-letter code ('en'). Defaults to English.","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location as a DFS name ('United States') or numeric code ('2840'). Defaults to the US.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Instrument identifier — re-feed into /v1/google_finance/quote (\"GOOGL:NASDAQ\" | \".INX:INDEXSP\" | \"EUR-USD\")"},"ticker":{"type":["string","null"],"description":"Ticker symbol (null for forex/crypto asset pairs)"},"exchange":{"type":["string","null"],"description":"Primary exchange / market identifier"},"name":{"type":["string","null"],"description":"Display name (e.g. 'Alphabet Inc Class A')"},"type":{"type":"string","description":"Instrument class: stock | etf | index | crypto | forex | futures | fund | unknown"},"url":{"type":["string","null"],"description":"String at quote.url"},"currency":{"type":["string","null"],"description":"Price currency (null for asset pairs)"},"pair":{"type":["object","null"],"description":"Forex/crypto base+quote symbols (null for stocks/indices)","properties":{"base_symbol":{"type":["string","null"],"description":"String at quote.pair.base_symbol"},"quote_symbol":{"type":["string","null"],"description":"String at quote.pair.quote_symbol"},"base_display_name":{"type":["string","null"],"description":"String at quote.pair.base_display_name"},"quote_display_name":{"type":["string","null"],"description":"String at quote.pair.quote_display_name"}}},"price":{"type":"object","description":"Price block (current, previous_close, delta, ranges, trend)","properties":{"current":{"type":["integer","null"],"description":"Numeric at quote.price.current"},"previous_close":{"type":["integer","null"],"description":"Numeric at quote.price.previous_close"},"delta":{"type":["integer","null"],"description":"Numeric at quote.price.delta"},"percentage_delta":{"type":["integer","null"],"description":"Numeric at quote.price.percentage_delta"},"trend":{"type":["string","null"],"description":"Leaf at quote.price.trend"},"day_low":{"type":["integer","null"],"description":"Numeric at quote.price.day_low"},"day_high":{"type":["integer","null"],"description":"Numeric at quote.price.day_high"},"year_low":{"type":["integer","null"],"description":"Numeric at quote.price.year_low"},"year_high":{"type":["integer","null"],"description":"Numeric at quote.price.year_high"},"timestamp":{"type":["string","null"],"description":"String at quote.price.timestamp"}}},"metrics":{"type":["object","null"],"description":"Fundamentals (market_cap, pe_ratio, dividend_yield, expense_ratio, …); null on thin rows","properties":{"market_cap":{"type":["integer","null"],"description":"Numeric at quote.metrics.market_cap"},"volume":{"type":["integer","null"],"description":"Numeric at quote.metrics.volume"},"avg_volume":{"type":["integer","null"],"description":"Numeric at quote.metrics.avg_volume"},"pe_ratio":{"type":["integer","null"],"description":"Numeric at quote.metrics.pe_ratio"},"dividend_yield":{"type":["integer","null"],"description":"Numeric at quote.metrics.dividend_yield"},"ytd_return":{"type":["integer","null"],"description":"Numeric at quote.metrics.ytd_return"},"expense_ratio":{"type":["integer","null"],"description":"Numeric at quote.metrics.expense_ratio"},"net_assets":{"type":["integer","null"],"description":"Numeric at quote.metrics.net_assets"},"yield":{"type":["integer","null"],"description":"Numeric at quote.metrics.yield"},"open_interest":{"type":["integer","null"],"description":"Numeric at quote.metrics.open_interest"},"category":{"type":["string","null"],"description":"String at quote.metrics.category"},"metrics_currency":{"type":["string","null"],"description":"String at quote.metrics.metrics_currency"}}},"about":{"type":["object","null"],"description":"Company profile (description, CEO, HQ, employees); equities","properties":{"description":{"type":["string","null"],"description":"String at quote.about.description"},"description_source_url":{"type":["string","null"],"description":"String at quote.about.description_source_url"},"ceo":{"type":["string","null"],"description":"String at quote.about.ceo"},"founded":{"type":["string","null"],"description":"String at quote.about.founded"},"headquarters":{"type":["string","null"],"description":"String at quote.about.headquarters"},"website":{"type":["string","null"],"description":"String at quote.about.website"},"employees":{"type":["integer","null"],"description":"Numeric at quote.about.employees"}}},"graph":{"type":["array","null"],"description":"Intraday price series ({ timestamp, value, volume })","items":{"type":"object","description":"Intraday price series ({ timestamp, value, volume })","properties":{"timestamp":{"type":"string","description":"String at quote.graph.timestamp"},"value":{"type":"integer","description":"Numeric at quote.graph.value"},"volume":{"type":["integer","null"],"description":"Numeric at quote.graph.volume"}}}},"financials":{"type":["object","null"],"description":"Quarterly + annual fundamentals (equities only; null otherwise)","properties":{"quarterly":{"type":["array","null"],"description":"Array at quote.financials.quarterly","items":{"type":"string","description":"Leaf at quote.financials.quarterly"}},"annual":{"type":["array","null"],"description":"Array at quote.financials.annual","items":{"type":"string","description":"Leaf at quote.financials.annual"}}}},"peers":{"type":["array","null"],"description":"Related instruments (compare_to)","items":{"type":"object","description":"Related instruments (compare_to)","properties":{"id":{"type":"string","description":"String at quote.peers.id"},"ticker":{"type":["string","null"],"description":"String at quote.peers.ticker"},"exchange":{"type":["string","null"],"description":"String at quote.peers.exchange"},"name":{"type":["string","null"],"description":"String at quote.peers.name"},"type":{"type":"string","description":"Leaf at quote.peers.type"},"url":{"type":["string","null"],"description":"String at quote.peers.url"},"currency":{"type":["string","null"],"description":"String at quote.peers.currency"},"pair":{"type":["object","null"],"description":"Nested object: quote.peers.pair","properties":{"base_symbol":{"type":["string","null"],"description":"String at quote.peers.pair.base_symbol"},"quote_symbol":{"type":["string","null"],"description":"String at quote.peers.pair.quote_symbol"},"base_display_name":{"type":["string","null"],"description":"String at quote.peers.pair.base_display_name"},"quote_display_name":{"type":["string","null"],"description":"String at quote.peers.pair.quote_display_name"}}},"price":{"type":"object","description":"Nested object: quote.peers.price","properties":{"current":{"type":["integer","null"],"description":"Numeric at quote.peers.price.current"},"previous_close":{"type":["integer","null"],"description":"Numeric at quote.peers.price.previous_close"},"delta":{"type":["integer","null"],"description":"Numeric at quote.peers.price.delta"},"percentage_delta":{"type":["integer","null"],"description":"Numeric at quote.peers.price.percentage_delta"},"trend":{"type":["string","null"],"description":"Leaf at quote.peers.price.trend"},"day_low":{"type":["integer","null"],"description":"Numeric at quote.peers.price.day_low"},"day_high":{"type":["integer","null"],"description":"Numeric at quote.peers.price.day_high"},"year_low":{"type":["integer","null"],"description":"Numeric at quote.peers.price.year_low"},"year_high":{"type":["integer","null"],"description":"Numeric at quote.peers.price.year_high"},"timestamp":{"type":["string","null"],"description":"String at quote.peers.price.timestamp"}}},"metrics":{"type":["object","null"],"description":"Nested object: quote.peers.metrics","properties":{"market_cap":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.market_cap"},"volume":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.volume"},"avg_volume":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.avg_volume"},"pe_ratio":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.pe_ratio"},"dividend_yield":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.dividend_yield"},"ytd_return":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.ytd_return"},"expense_ratio":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.expense_ratio"},"net_assets":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.net_assets"},"yield":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.yield"},"open_interest":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.open_interest"},"category":{"type":["string","null"],"description":"String at quote.peers.metrics.category"},"metrics_currency":{"type":["string","null"],"description":"String at quote.peers.metrics.metrics_currency"}}}}}},"ext":{"type":["string","null"],"description":"Leaf at quote.ext"}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_finance/ticker-search":{"get":{"summary":"Search financial instruments by name","description":"Searches Google Finance for financial instruments matching a name and returns a unified QuoteList — each row carries the `id` (e.g. 'AAPL:NASDAQ', '.INX:INDEXSP', 'EUR-USD') to feed into /v1/google_finance/quote, plus the ticker, display name, exchange, live price, and `type` discriminator. Spans stocks, ETFs, indices, and forex/crypto pairs (asset pairs populate `quote.pair`, with a null `ticker`). Filter by instrument class with `category`. Sourced live from DataForSEO's Google Finance SERP (~2-3s).","tags":["google_finance"],"operationId":"get_google_finance_ticker_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"keyword","in":"query","required":true,"description":"Company / instrument name to search for (e.g. 'Apple', 'Euro', 'Bitcoin').","schema":{"type":"string"},"example":"Apple"},{"name":"category","in":"query","required":false,"description":"Restrict to one instrument class: all (default), stock, index, mutual_fund, currency, or futures. A class with no matches returns an empty list.","schema":{"type":"string","enum":["all","stock","index","mutual_fund","currency","futures"]}},{"name":"language","in":"query","required":false,"description":"Language as a DFS name ('English') or 2-letter code ('en'). Defaults to English.","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location as a DFS name ('United States') or numeric code ('2840'). Defaults to the US.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical quote wrappers ({ quote })","items":{"type":"object","description":"Canonical quote wrapper","properties":{"quote":{"type":"object","description":"Canonical Quote object (unified across financial instruments)","properties":{"id":{"type":"string","description":"Instrument identifier — re-feed into /v1/google_finance/quote (\"GOOGL:NASDAQ\" | \".INX:INDEXSP\" | \"EUR-USD\")"},"ticker":{"type":["string","null"],"description":"Ticker symbol (null for forex/crypto asset pairs)"},"exchange":{"type":["string","null"],"description":"Primary exchange / market identifier"},"name":{"type":["string","null"],"description":"Display name (e.g. 'Alphabet Inc Class A')"},"type":{"type":"string","description":"Instrument class: stock | etf | index | crypto | forex | futures | fund | unknown"},"url":{"type":["string","null"],"description":"String at quote.url"},"currency":{"type":["string","null"],"description":"Price currency (null for asset pairs)"},"pair":{"type":["object","null"],"description":"Forex/crypto base+quote symbols (null for stocks/indices)","properties":{"base_symbol":{"type":["string","null"],"description":"String at quote.pair.base_symbol"},"quote_symbol":{"type":["string","null"],"description":"String at quote.pair.quote_symbol"},"base_display_name":{"type":["string","null"],"description":"String at quote.pair.base_display_name"},"quote_display_name":{"type":["string","null"],"description":"String at quote.pair.quote_display_name"}}},"price":{"type":"object","description":"Price block (current, previous_close, delta, ranges, trend)","properties":{"current":{"type":["integer","null"],"description":"Numeric at quote.price.current"},"previous_close":{"type":["integer","null"],"description":"Numeric at quote.price.previous_close"},"delta":{"type":["integer","null"],"description":"Numeric at quote.price.delta"},"percentage_delta":{"type":["integer","null"],"description":"Numeric at quote.price.percentage_delta"},"trend":{"type":["string","null"],"description":"Leaf at quote.price.trend"},"day_low":{"type":["integer","null"],"description":"Numeric at quote.price.day_low"},"day_high":{"type":["integer","null"],"description":"Numeric at quote.price.day_high"},"year_low":{"type":["integer","null"],"description":"Numeric at quote.price.year_low"},"year_high":{"type":["integer","null"],"description":"Numeric at quote.price.year_high"},"timestamp":{"type":["string","null"],"description":"String at quote.price.timestamp"}}},"metrics":{"type":["object","null"],"description":"Fundamentals (market_cap, pe_ratio, dividend_yield, expense_ratio, …); null on thin rows","properties":{"market_cap":{"type":["integer","null"],"description":"Numeric at quote.metrics.market_cap"},"volume":{"type":["integer","null"],"description":"Numeric at quote.metrics.volume"},"avg_volume":{"type":["integer","null"],"description":"Numeric at quote.metrics.avg_volume"},"pe_ratio":{"type":["integer","null"],"description":"Numeric at quote.metrics.pe_ratio"},"dividend_yield":{"type":["integer","null"],"description":"Numeric at quote.metrics.dividend_yield"},"ytd_return":{"type":["integer","null"],"description":"Numeric at quote.metrics.ytd_return"},"expense_ratio":{"type":["integer","null"],"description":"Numeric at quote.metrics.expense_ratio"},"net_assets":{"type":["integer","null"],"description":"Numeric at quote.metrics.net_assets"},"yield":{"type":["integer","null"],"description":"Numeric at quote.metrics.yield"},"open_interest":{"type":["integer","null"],"description":"Numeric at quote.metrics.open_interest"},"category":{"type":["string","null"],"description":"String at quote.metrics.category"},"metrics_currency":{"type":["string","null"],"description":"String at quote.metrics.metrics_currency"}}},"about":{"type":["object","null"],"description":"Company profile (description, CEO, HQ, employees); equities","properties":{"description":{"type":["string","null"],"description":"String at quote.about.description"},"description_source_url":{"type":["string","null"],"description":"String at quote.about.description_source_url"},"ceo":{"type":["string","null"],"description":"String at quote.about.ceo"},"founded":{"type":["string","null"],"description":"String at quote.about.founded"},"headquarters":{"type":["string","null"],"description":"String at quote.about.headquarters"},"website":{"type":["string","null"],"description":"String at quote.about.website"},"employees":{"type":["integer","null"],"description":"Numeric at quote.about.employees"}}},"graph":{"type":["array","null"],"description":"Intraday price series ({ timestamp, value, volume })","items":{"type":"object","description":"Intraday price series ({ timestamp, value, volume })","properties":{"timestamp":{"type":"string","description":"String at quote.graph.timestamp"},"value":{"type":"integer","description":"Numeric at quote.graph.value"},"volume":{"type":["integer","null"],"description":"Numeric at quote.graph.volume"}}}},"financials":{"type":["object","null"],"description":"Quarterly + annual fundamentals (equities only; null otherwise)","properties":{"quarterly":{"type":["array","null"],"description":"Array at quote.financials.quarterly","items":{"type":"string","description":"Leaf at quote.financials.quarterly"}},"annual":{"type":["array","null"],"description":"Array at quote.financials.annual","items":{"type":"string","description":"Leaf at quote.financials.annual"}}}},"peers":{"type":["array","null"],"description":"Related instruments (compare_to)","items":{"type":"object","description":"Related instruments (compare_to)","properties":{"id":{"type":"string","description":"String at quote.peers.id"},"ticker":{"type":["string","null"],"description":"String at quote.peers.ticker"},"exchange":{"type":["string","null"],"description":"String at quote.peers.exchange"},"name":{"type":["string","null"],"description":"String at quote.peers.name"},"type":{"type":"string","description":"Leaf at quote.peers.type"},"url":{"type":["string","null"],"description":"String at quote.peers.url"},"currency":{"type":["string","null"],"description":"String at quote.peers.currency"},"pair":{"type":["object","null"],"description":"Nested object: quote.peers.pair","properties":{"base_symbol":{"type":["string","null"],"description":"String at quote.peers.pair.base_symbol"},"quote_symbol":{"type":["string","null"],"description":"String at quote.peers.pair.quote_symbol"},"base_display_name":{"type":["string","null"],"description":"String at quote.peers.pair.base_display_name"},"quote_display_name":{"type":["string","null"],"description":"String at quote.peers.pair.quote_display_name"}}},"price":{"type":"object","description":"Nested object: quote.peers.price","properties":{"current":{"type":["integer","null"],"description":"Numeric at quote.peers.price.current"},"previous_close":{"type":["integer","null"],"description":"Numeric at quote.peers.price.previous_close"},"delta":{"type":["integer","null"],"description":"Numeric at quote.peers.price.delta"},"percentage_delta":{"type":["integer","null"],"description":"Numeric at quote.peers.price.percentage_delta"},"trend":{"type":["string","null"],"description":"Leaf at quote.peers.price.trend"},"day_low":{"type":["integer","null"],"description":"Numeric at quote.peers.price.day_low"},"day_high":{"type":["integer","null"],"description":"Numeric at quote.peers.price.day_high"},"year_low":{"type":["integer","null"],"description":"Numeric at quote.peers.price.year_low"},"year_high":{"type":["integer","null"],"description":"Numeric at quote.peers.price.year_high"},"timestamp":{"type":["string","null"],"description":"String at quote.peers.price.timestamp"}}},"metrics":{"type":["object","null"],"description":"Nested object: quote.peers.metrics","properties":{"market_cap":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.market_cap"},"volume":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.volume"},"avg_volume":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.avg_volume"},"pe_ratio":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.pe_ratio"},"dividend_yield":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.dividend_yield"},"ytd_return":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.ytd_return"},"expense_ratio":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.expense_ratio"},"net_assets":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.net_assets"},"yield":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.yield"},"open_interest":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.open_interest"},"category":{"type":["string","null"],"description":"String at quote.peers.metrics.category"},"metrics_currency":{"type":["string","null"],"description":"String at quote.peers.metrics.metrics_currency"}}}}}},"ext":{"type":["string","null"],"description":"Leaf at quote.ext"}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_finance/markets":{"get":{"summary":"Get a markets overview (indices + movers)","description":"Returns a unified QuoteList snapshot of the global markets overview: the major regional indices (US / Europe / Asia, tagged in `quote.ext.section`) plus the day's most-active, gainers, and losers movers. Each row is the same canonical Quote shape used everywhere — re-feed any `id` into /v1/google_finance/quote for the full detail. A standing overview (no input required); the regional grouping is baked into the single response. Sourced live from DataForSEO's Google Finance SERP (~4-8s).","tags":["google_finance"],"operationId":"get_google_finance_markets","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"language","in":"query","required":false,"description":"Language as a DFS name ('English') or 2-letter code ('en'). Defaults to English.","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location as a DFS name ('United States') or numeric code ('2840'). Defaults to the US.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical quote wrappers ({ quote })","items":{"type":"object","description":"Canonical quote wrapper","properties":{"quote":{"type":"object","description":"Canonical Quote object (unified across financial instruments)","properties":{"id":{"type":"string","description":"Instrument identifier — re-feed into /v1/google_finance/quote (\"GOOGL:NASDAQ\" | \".INX:INDEXSP\" | \"EUR-USD\")"},"ticker":{"type":["string","null"],"description":"Ticker symbol (null for forex/crypto asset pairs)"},"exchange":{"type":["string","null"],"description":"Primary exchange / market identifier"},"name":{"type":["string","null"],"description":"Display name (e.g. 'Alphabet Inc Class A')"},"type":{"type":"string","description":"Instrument class: stock | etf | index | crypto | forex | futures | fund | unknown"},"url":{"type":["string","null"],"description":"String at quote.url"},"currency":{"type":["string","null"],"description":"Price currency (null for asset pairs)"},"pair":{"type":["object","null"],"description":"Forex/crypto base+quote symbols (null for stocks/indices)","properties":{"base_symbol":{"type":["string","null"],"description":"String at quote.pair.base_symbol"},"quote_symbol":{"type":["string","null"],"description":"String at quote.pair.quote_symbol"},"base_display_name":{"type":["string","null"],"description":"String at quote.pair.base_display_name"},"quote_display_name":{"type":["string","null"],"description":"String at quote.pair.quote_display_name"}}},"price":{"type":"object","description":"Price block (current, previous_close, delta, ranges, trend)","properties":{"current":{"type":["integer","null"],"description":"Numeric at quote.price.current"},"previous_close":{"type":["integer","null"],"description":"Numeric at quote.price.previous_close"},"delta":{"type":["integer","null"],"description":"Numeric at quote.price.delta"},"percentage_delta":{"type":["integer","null"],"description":"Numeric at quote.price.percentage_delta"},"trend":{"type":["string","null"],"description":"Leaf at quote.price.trend"},"day_low":{"type":["integer","null"],"description":"Numeric at quote.price.day_low"},"day_high":{"type":["integer","null"],"description":"Numeric at quote.price.day_high"},"year_low":{"type":["integer","null"],"description":"Numeric at quote.price.year_low"},"year_high":{"type":["integer","null"],"description":"Numeric at quote.price.year_high"},"timestamp":{"type":["string","null"],"description":"String at quote.price.timestamp"}}},"metrics":{"type":["object","null"],"description":"Fundamentals (market_cap, pe_ratio, dividend_yield, expense_ratio, …); null on thin rows","properties":{"market_cap":{"type":["integer","null"],"description":"Numeric at quote.metrics.market_cap"},"volume":{"type":["integer","null"],"description":"Numeric at quote.metrics.volume"},"avg_volume":{"type":["integer","null"],"description":"Numeric at quote.metrics.avg_volume"},"pe_ratio":{"type":["integer","null"],"description":"Numeric at quote.metrics.pe_ratio"},"dividend_yield":{"type":["integer","null"],"description":"Numeric at quote.metrics.dividend_yield"},"ytd_return":{"type":["integer","null"],"description":"Numeric at quote.metrics.ytd_return"},"expense_ratio":{"type":["integer","null"],"description":"Numeric at quote.metrics.expense_ratio"},"net_assets":{"type":["integer","null"],"description":"Numeric at quote.metrics.net_assets"},"yield":{"type":["integer","null"],"description":"Numeric at quote.metrics.yield"},"open_interest":{"type":["integer","null"],"description":"Numeric at quote.metrics.open_interest"},"category":{"type":["string","null"],"description":"String at quote.metrics.category"},"metrics_currency":{"type":["string","null"],"description":"String at quote.metrics.metrics_currency"}}},"about":{"type":["object","null"],"description":"Company profile (description, CEO, HQ, employees); equities","properties":{"description":{"type":["string","null"],"description":"String at quote.about.description"},"description_source_url":{"type":["string","null"],"description":"String at quote.about.description_source_url"},"ceo":{"type":["string","null"],"description":"String at quote.about.ceo"},"founded":{"type":["string","null"],"description":"String at quote.about.founded"},"headquarters":{"type":["string","null"],"description":"String at quote.about.headquarters"},"website":{"type":["string","null"],"description":"String at quote.about.website"},"employees":{"type":["integer","null"],"description":"Numeric at quote.about.employees"}}},"graph":{"type":["array","null"],"description":"Intraday price series ({ timestamp, value, volume })","items":{"type":"object","description":"Intraday price series ({ timestamp, value, volume })","properties":{"timestamp":{"type":"string","description":"String at quote.graph.timestamp"},"value":{"type":"integer","description":"Numeric at quote.graph.value"},"volume":{"type":["integer","null"],"description":"Numeric at quote.graph.volume"}}}},"financials":{"type":["object","null"],"description":"Quarterly + annual fundamentals (equities only; null otherwise)","properties":{"quarterly":{"type":["array","null"],"description":"Array at quote.financials.quarterly","items":{"type":"string","description":"Leaf at quote.financials.quarterly"}},"annual":{"type":["array","null"],"description":"Array at quote.financials.annual","items":{"type":"string","description":"Leaf at quote.financials.annual"}}}},"peers":{"type":["array","null"],"description":"Related instruments (compare_to)","items":{"type":"object","description":"Related instruments (compare_to)","properties":{"id":{"type":"string","description":"String at quote.peers.id"},"ticker":{"type":["string","null"],"description":"String at quote.peers.ticker"},"exchange":{"type":["string","null"],"description":"String at quote.peers.exchange"},"name":{"type":["string","null"],"description":"String at quote.peers.name"},"type":{"type":"string","description":"Leaf at quote.peers.type"},"url":{"type":["string","null"],"description":"String at quote.peers.url"},"currency":{"type":["string","null"],"description":"String at quote.peers.currency"},"pair":{"type":["object","null"],"description":"Nested object: quote.peers.pair","properties":{"base_symbol":{"type":["string","null"],"description":"String at quote.peers.pair.base_symbol"},"quote_symbol":{"type":["string","null"],"description":"String at quote.peers.pair.quote_symbol"},"base_display_name":{"type":["string","null"],"description":"String at quote.peers.pair.base_display_name"},"quote_display_name":{"type":["string","null"],"description":"String at quote.peers.pair.quote_display_name"}}},"price":{"type":"object","description":"Nested object: quote.peers.price","properties":{"current":{"type":["integer","null"],"description":"Numeric at quote.peers.price.current"},"previous_close":{"type":["integer","null"],"description":"Numeric at quote.peers.price.previous_close"},"delta":{"type":["integer","null"],"description":"Numeric at quote.peers.price.delta"},"percentage_delta":{"type":["integer","null"],"description":"Numeric at quote.peers.price.percentage_delta"},"trend":{"type":["string","null"],"description":"Leaf at quote.peers.price.trend"},"day_low":{"type":["integer","null"],"description":"Numeric at quote.peers.price.day_low"},"day_high":{"type":["integer","null"],"description":"Numeric at quote.peers.price.day_high"},"year_low":{"type":["integer","null"],"description":"Numeric at quote.peers.price.year_low"},"year_high":{"type":["integer","null"],"description":"Numeric at quote.peers.price.year_high"},"timestamp":{"type":["string","null"],"description":"String at quote.peers.price.timestamp"}}},"metrics":{"type":["object","null"],"description":"Nested object: quote.peers.metrics","properties":{"market_cap":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.market_cap"},"volume":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.volume"},"avg_volume":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.avg_volume"},"pe_ratio":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.pe_ratio"},"dividend_yield":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.dividend_yield"},"ytd_return":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.ytd_return"},"expense_ratio":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.expense_ratio"},"net_assets":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.net_assets"},"yield":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.yield"},"open_interest":{"type":["integer","null"],"description":"Numeric at quote.peers.metrics.open_interest"},"category":{"type":["string","null"],"description":"String at quote.peers.metrics.category"},"metrics_currency":{"type":["string","null"],"description":"String at quote.peers.metrics.metrics_currency"}}}}}},"ext":{"type":["string","null"],"description":"Leaf at quote.ext"}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_trends/explore":{"get":{"summary":"Get Google Trends interest over time","description":"Returns Google Trends interest-over-time for up to 5 keywords in one call. Response is `{ series, averages }`: `series` is one entry per keyword, each with dated `points` ({ date, value }) where `value` is Google's 0-100 relative-popularity score; `averages` is the per-keyword mean over the window. Compare terms head-to-head (values are normalised across the keyword set) and scope by `location`, `timeframe`, and `category`. Sourced live from DataForSEO's Google Trends Explore (~3-8s).","tags":["google_trends"],"operationId":"get_google_trends_explore","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"keywords","in":"query","required":true,"description":"1-5 comma-separated keywords (e.g. 'reverse audio,voice changer'). With multiple keywords the 0-100 values are normalised across the set for direct comparison.","schema":{"type":"string"},"example":"uv index"},{"name":"location","in":"query","required":false,"description":"Location as a DFS name ('United States') or numeric code ('2840'). Defaults to worldwide-leaning US.","schema":{"type":"string"}},{"name":"timeframe","in":"query","required":false,"description":"Preset time window: past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, or past_5_years. Defaults to past_12_months.","schema":{"type":"string","enum":["past_hour","past_4_hours","past_day","past_7_days","past_30_days","past_90_days","past_12_months","past_5_years"]},"example":"past_90_days"},{"name":"category","in":"query","required":false,"description":"Numeric Google Trends category code to scope the query (default 0 = all categories).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_trends/rising":{"get":{"summary":"Get related + rising Google Trends queries","description":"Returns the related search queries for ONE keyword as `{ rising, top }`. `rising` is the breakout list — queries whose search interest grew the most over the window, each with a `growth` percentage (a true breakout can read into the thousands, e.g. 3200 = +3200%); `top` is the most-searched related queries, each with a 0-100 relative `value`. The closest thing to a 'breakout terms' primitive — pair it with /v1/google_trends/explore to size a trend and find the queries driving it. Sourced live from DataForSEO's Google Trends Explore (~3-8s).","tags":["google_trends"],"operationId":"get_google_trends_rising","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"keyword","in":"query","required":true,"description":"Single keyword to expand (e.g. 'uv index'). Google Trends returns the related-queries list for one keyword only.","schema":{"type":"string"},"example":"uv index"},{"name":"location","in":"query","required":false,"description":"Location as a DFS name ('United States') or numeric code ('2840'). Defaults to worldwide-leaning US.","schema":{"type":"string"}},{"name":"timeframe","in":"query","required":false,"description":"Preset time window: past_hour, past_4_hours, past_day, past_7_days, past_30_days, past_90_days, past_12_months, or past_5_years. Defaults to past_12_months.","schema":{"type":"string","enum":["past_hour","past_4_hours","past_day","past_7_days","past_30_days","past_90_days","past_12_months","past_5_years"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/trustpilot/business-search":{"get":{"summary":"Search Trustpilot businesses","description":"Searches Trustpilot for businesses (companies) matching a keyword. Returns a unified AuthorList — each result is a business profile with its display name, Trustpilot domain (`username`/`id`), own website (`external_url`), Trustpilot review-page URL (`url`), and total Trustpilot review count (`posts_count`). Use the returned domain to pull that business's reviews via /v1/trustpilot/reviews. Note: search matches BUSINESSES, not products — a domain-shaped query returns no results. Sourced from DataForSEO's task-based Business Data API; the async lifecycle is handled server-side, so this is an ordinary synchronous request (first calls take ~15-45s, then serve from cache).","tags":["trustpilot"],"operationId":"get_trustpilot_business_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Business name or keyword (e.g. 'nike'). Matches companies, not products; do not pass a bare domain.","schema":{"type":"string"},"example":"nike"},{"name":"depth","in":"query","required":false,"description":"Number of business results to retrieve (default 20, multiples of 10, max 140). More results = longer task time.","schema":{"type":"integer"},"example":20},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical author wrappers ({ author })","items":{"type":"object","description":"Canonical author wrapper","properties":{"author":{"type":"object","description":"Canonical Author object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/search/users","data":{"items":[{"author":{"id":"6780262640079193090","username":"cookingwithhel","display_name":"Cooking with Hel","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/e1547b843ed71ccc69e199147854f489~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=7f24701a&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=bLp06YEEM1DEDR6nG%2BZt3lhGWx4%3D","bio":null,"verified":null,"followers":4214875,"following":1,"posts_count":2341,"likes_count":62731828,"url":null,"location":null}},{"author":{"id":"7352666564073833515","username":"cooking_recipescr","display_name":"cooking_recipescr","avatar_url":"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7352667004160966699~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=6df0f827&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=ysLi7%2FLtH4t5ebZnGzJXSfgYhnU%3D","bio":null,"verified":null,"followers":1780390,"following":1,"posts_count":995,"likes_count":10060260,"url":null,"location":null}},{"author":{"id":"6829580668634694662","username":"felizcooking","display_name":"Feliz Cooking","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/179d2c1fe2dc5523974abdaf232e8554~tplv-tiktokx-cropcenter-q:100:100:q70.heic?biz_tag=musically_user.user_cover&dr=8835&idc=useast8&ps=87d6e48a&refresh_token=97c11cfd&s=SEARCH&sc=avatar&shcp=c1333099&shp=30310797&t=223449c4&x-expires=1783202400&x-signature=aCkp4jy6AxdG2R9otN52rtXzHNc%3D","bio":null,"verified":null,"followers":338243,"following":374,"posts_count":464,"likes_count":2140124,"url":null,"location":null}}],"next_cursor":"30","total":30},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0","has_more":true,"page_size":30}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/trustpilot/reviews":{"get":{"summary":"Get Trustpilot reviews for a business","description":"Returns a unified ReviewList of customer reviews for a business on Trustpilot, keyed by its domain (`entity_id` on every review). Each review carries the star rating, full text, title, verified-status, language (reviews arrive in many languages — filter client-side via `language`), reviewer profile, owner/brand `responses[]`, and publish date. Reviews are about the COMPANY (shipping, refunds, support), never a specific product — for product reviews use /v1/google_shopping/reviews or /v1/amazon/reviews. Get the domain from /v1/trustpilot/business-search. The platform exposes no deeper pagination — `depth` caps at 200 (the most recent / most relevant); a business with no Trustpilot reviews returns 404 (auto-refunded). Sourced from DataForSEO's task-based Business Data API (first calls ~15-45s, then cached).","tags":["trustpilot"],"operationId":"get_trustpilot_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"domain","in":"query","required":true,"description":"The business's domain on Trustpilot (e.g. 'www.nike.com' or 'booking.com'), from business-search.","schema":{"type":"string"},"example":"www.nike.com"},{"name":"depth","in":"query","required":false,"description":"Number of reviews to retrieve (default 20, multiples of 20, max 200). There is no pagination beyond 200.","schema":{"type":"integer"},"example":20},{"name":"sort","in":"query","required":false,"description":"Review ordering: `recency` (newest first, default) or `relevance`.","schema":{"type":"string","enum":["recency","relevance"]},"example":"recency"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/app-search":{"get":{"summary":"Search Google Play apps by keyword","description":"Returns a unified AppList of Google Play apps matching a keyword — title, icon, developer, rating, price/is_free, and store URL on every item, on the same canonical `App` shape used across every app marketplace (`app.store` = \"google_play\"). Detail-only fields (description, screenshots, installs) are null on search items; fetch /v1/google_play/app-info for the full record. Sourced from DataForSEO's task-based App Data API (first calls ~7-15s, then cached).","tags":["google_play"],"operationId":"get_google_play_app_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword (e.g. 'photo editor').","schema":{"type":"string"},"example":"photo editor"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name ('United States') or numeric location code ('2840'). Defaults to the US.","schema":{"type":"string"},"example":"United States"},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of results to retrieve (default 30, rounded up to multiples of 30, max 300).","schema":{"type":"integer"},"example":30},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical app wrappers ({ app })","items":{"type":"object","description":"Canonical app wrapper","properties":{"app":{"type":"object","description":"Canonical App object (unified across app marketplaces)","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/search-suggestions":{"get":{"summary":"Get Google Play search suggestions","description":"Returns Google Play's search autocomplete suggestions for a keyword stem — the same terms the store's search box surfaces. The day Play starts autocompleting a phrase, real demand exists; poll a stem daily and diff to catch rising app keywords early. Each item is `{ term, priority }` ranked by Play's own order (Play exposes no numeric score). Returns a list under `items`.","tags":["google_play"],"operationId":"get_google_play_search_suggestions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Partial search keyword to autocomplete (e.g. 'reverse').","schema":{"type":"string"},"example":"reverse"},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 storefront country code. Defaults to 'us'.","schema":{"type":"string"},"example":"us"},{"name":"language","in":"query","required":false,"description":"ISO 639-1 language code. Defaults to 'en'.","schema":{"type":"string"},"example":"en"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/app-info":{"get":{"summary":"Get full Google Play app details","description":"Returns the full canonical `App` record for one Google Play app keyed by its package name (`app_id`) — title, description, developer block (incl. email/address/website), rating, price, install count + display ('1,000,000,000+'), version, size, screenshots, genres, chart tags, similar apps, and update date. The `app.store` field is always \"google_play\"; Apple-only leaves (advisories, languages) are null. Get the `app_id` from /v1/google_play/app-search. Sourced from DataForSEO's task-based App Data API.","tags":["google_play"],"operationId":"get_google_play_app_info","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"app_id","in":"query","required":true,"description":"Google Play package name (e.g. 'com.spotify.music'), from app-search.","schema":{"type":"string"},"example":"com.spotify.music"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"},"example":"United States"},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/app-reviews":{"get":{"summary":"Get Google Play reviews for an app","description":"Returns a unified ReviewList of Google Play user reviews for an app, keyed by its package name (`app_id` on every review's `entity_id`). Each review carries the star rating, full text, reviewer name + avatar, helpful-vote count, developer `responses[]` (reply text + date), and publish date — on the SAME canonical `Review` shape used by Amazon, Google Shopping, and Trustpilot. Google reviews have no title (always null). `depth` returns reviews in batches of 150 (max 600). Sourced from DataForSEO's task-based App Data API.","tags":["google_play"],"operationId":"get_google_play_app_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"app_id","in":"query","required":true,"description":"Google Play package name (e.g. 'com.spotify.music'), from app-search.","schema":{"type":"string"},"example":"com.spotify.music"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of reviews to retrieve (default 150, batches of 150, max 600).","schema":{"type":"integer"},"example":150},{"name":"sort_by","in":"query","required":false,"description":"Review ordering: `newest` (default) or `most_relevant`.","schema":{"type":"string","enum":["newest","most_relevant"]},"example":"newest"},{"name":"rating","in":"query","required":false,"description":"Filter to a single star rating (1–5).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/app-list":{"get":{"summary":"Get a Google Play store chart","description":"Returns a unified AppList for a Google Play store chart (top free, top paid, top grossing, movers & shakers, etc.), optionally scoped to a category. Each item is the same canonical `App` shape as app-search. Use it to track ranking movements or build a category leaderboard. Sourced from DataForSEO's task-based App Data API.","tags":["google_play"],"operationId":"get_google_play_app_list","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"app_collection","in":"query","required":true,"description":"Chart to retrieve: topselling_free, topselling_paid, topgrossing, movers_shakers, topselling_new_free, topselling_new_paid.","schema":{"type":"string"},"example":"topselling_free"},{"name":"app_category","in":"query","required":false,"description":"Optional Google Play category to scope the chart (e.g. 'photography', 'game_puzzle').","schema":{"type":"string","enum":["art_and_design","auto_and_vehicles","beauty","books_and_reference","business","comics","communication","dating","education","entertainment","events","finance","food_and_drink","health_and_fitness","house_and_home","libraries_and_demo","lifestyle","maps_and_navigation","medical","music_and_audio","news_and_magazines","parenting","personalization","photography","productivity","shopping","social","sports","tools","travel_and_local","video_players","android_wear","watch_face","weather","game","game_action","game_adventure","game_arcade","game_board","game_card","game_casino","game_casual","game_educational","game_music","game_puzzle","game_racing","game_role_playing","game_simulation","game_sports","game_strategy","game_trivia","game_word","family"]},"example":"photography"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of apps to retrieve (default 100, max 500).","schema":{"type":"integer"},"example":100},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical app wrappers ({ app })","items":{"type":"object","description":"Canonical app wrapper","properties":{"app":{"type":"object","description":"Canonical App object (unified across app marketplaces)","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/app-listings-search":{"get":{"summary":"Search the Google Play listings database (paginated)","description":"Searches DataForSEO's real-time, filterable Google Play listings database by app title (and/or description) and returns a unified AppList. Unlike the store-chart endpoints this one is the ONE true paginator — page with `limit` (≤50) + `offset` (then `offset_token` for deeper) and read the platform-wide `total`. Premium-tier because the upstream bills per returned item. Sourced from DataForSEO's synchronous live App Data database.","tags":["google_play"],"operationId":"get_google_play_app_listings_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"title","in":"query","required":true,"description":"App title to search for (e.g. 'photo editor').","schema":{"type":"string"},"example":"photo editor"},{"name":"description","in":"query","required":false,"description":"Optional app-description text to match.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Apps per page (1–50, default 20).","schema":{"type":"integer"},"example":20},{"name":"offset","in":"query","required":false,"description":"Pagination offset (up to 10,000; use offset_token beyond).","schema":{"type":"integer"}},{"name":"offset_token","in":"query","required":false,"description":"Opaque deep-pagination cursor from a prior response.","schema":{"type":"string"}},{"name":"filters","in":"query","required":false,"description":"Advanced DataForSEO filter expression as a JSON array.","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical app wrappers ({ app })","items":{"type":"object","description":"Canonical app wrapper","properties":{"app":{"type":"object","description":"Canonical App object (unified across app marketplaces)","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/categories":{"get":{"summary":"List Google Play app categories","description":"Returns the list of Google Play app categories used by the `app_category` filter on /v1/google_play/app-list. Static reference data — heavily cached.","tags":["google_play"],"operationId":"get_google_play_categories","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/locations":{"get":{"summary":"List supported Google Play storefront locations","description":"Returns the locations (name + numeric location code) supported by the Google Play App Data endpoints. Use a code or name as the `country` param. Static reference data — heavily cached.","tags":["google_play"],"operationId":"get_google_play_locations","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/google_play/languages":{"get":{"summary":"List supported Google Play languages","description":"Returns the languages (name + code) supported by the Google Play App Data endpoints. Use a code as the `language` param. Static reference data — heavily cached.","tags":["google_play"],"operationId":"get_google_play_languages","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/app-search":{"get":{"summary":"Search Apple App Store apps by keyword","description":"Returns a unified AppList of Apple App Store apps matching a keyword — title, icon, rating, price/is_free, and store URL on every item, on the same canonical `App` shape used across every app marketplace (`app.store` = \"app_store\"). Detail-only fields (description, screenshots, developer) are null on search items; fetch /v1/app_store/app-info for the full record. Sourced from DataForSEO's task-based App Data API (first calls ~7-15s, then cached).","tags":["app_store"],"operationId":"get_app_store_app_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"Search keyword (e.g. 'photo editor').","schema":{"type":"string"},"example":"photo editor"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name ('United States') or numeric location code ('2840'). Defaults to the US.","schema":{"type":"string"},"example":"United States"},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of results to retrieve (default 100, rounded up to multiples of 100, max 300).","schema":{"type":"integer"},"example":100},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical app wrappers ({ app })","items":{"type":"object","description":"Canonical app wrapper","properties":{"app":{"type":"object","description":"Canonical App object (unified across app marketplaces)","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/search-suggestions":{"get":{"summary":"Get Apple App Store search suggestions","description":"Returns Apple's App Store search autocomplete ('search hints') for a keyword stem — the same suggestions the store's search box surfaces, ranked by Apple's own priority. The day Apple starts autocompleting a phrase, real demand exists; poll a stem daily and diff to catch rising app keywords early. Each item is `{ term, priority }` where `priority` is the 1-based upstream rank (Apple exposes no numeric score). Returns a list under `items`.","tags":["app_store"],"operationId":"get_app_store_search_suggestions","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Partial search keyword to autocomplete (e.g. 'reverse').","schema":{"type":"string"},"example":"reverse"},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 storefront country code. Defaults to 'us'.","schema":{"type":"string"},"example":"us"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/app-info":{"get":{"summary":"Get full Apple App Store app details","description":"Returns the full canonical `App` record for one Apple App Store app keyed by its numeric `app_id` — title, description, developer, rating, price, version, minimum iOS version, size, screenshots, supported languages, age advisories, similar apps, and update date. The `app.store` field is always \"app_store\"; Google-only leaves (installs, genres, developer email/address) are null, and `released_at` is null (Apple deprecates it). Get the `app_id` from /v1/app_store/app-search. Sourced from DataForSEO's task-based App Data API.","tags":["app_store"],"operationId":"get_app_store_app_info","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"app_id","in":"query","required":true,"description":"Apple App Store numeric app id (e.g. '324684580'), from app-search.","schema":{"type":"string"},"example":"324684580"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"},"example":"United States"},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/app-reviews":{"get":{"summary":"Get Apple App Store reviews for an app","description":"Returns a unified ReviewList of Apple App Store user reviews for an app, keyed by its numeric `app_id` (on every review's `entity_id`). Each review carries the star rating, full text, review title, reviewer name, and publish date — on the SAME canonical `Review` shape used by Amazon, Google Shopping, and Trustpilot. Apple reviews have no avatar, helpful-vote count, or developer responses (those are null). `depth` returns reviews in batches of 50 (max 600). Sourced from DataForSEO's task-based App Data API.","tags":["app_store"],"operationId":"get_app_store_app_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"app_id","in":"query","required":true,"description":"Apple App Store numeric app id (e.g. '324684580'), from app-search.","schema":{"type":"string"},"example":"324684580"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of reviews to retrieve (default 50, batches of 50, max 600).","schema":{"type":"integer"},"example":50},{"name":"sort_by","in":"query","required":false,"description":"Review ordering: `most_recent` (default) or `most_helpful`.","schema":{"type":"string","enum":["most_recent","most_helpful"]},"example":"most_recent"},{"name":"rating","in":"query","required":false,"description":"Filter to a single star rating (1–5).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/app-list":{"get":{"summary":"Get an Apple App Store chart","description":"Returns a unified AppList for an Apple App Store chart (top free, top paid, top grossing for iPhone or iPad, new apps), optionally scoped to a category. Each item is the same canonical `App` shape as app-search. Use it to track ranking movements or build a category leaderboard. Sourced from DataForSEO's task-based App Data API.","tags":["app_store"],"operationId":"get_app_store_app_list","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"app_collection","in":"query","required":true,"description":"Chart to retrieve: top_free_ios, top_paid_ios, top_grossing_ios, top_free_ipad, top_paid_ipad, top_grossing_ipad, new_ios, new_free_ios, new_paid_ios.","schema":{"type":"string"},"example":"top_free_ios"},{"name":"app_category","in":"query","required":false,"description":"Optional Apple App Store category to scope the chart (e.g. 'photo_and_video', 'games_puzzle').","schema":{"type":"string","enum":["books","business","catalogs","education","entertainment","finance","food_and_drink","games","games_action","games_adventure","games_arcade","games_board","games_card","games_casino","games_dice","games_educational","games_family","games_music","games_puzzle","games_racing","games_role_playing","games_simulation","games_sports","games_strategy","games_trivia","games_word","health_and_fitness","lifestyle","magazines_and_newspapers","magazines_arts","magazines_automotive","magazines_weddings","magazines_business","magazines_children","magazines_computer","magazines_food","magazines_crafts","magazines_electronics","magazines_entertainment","magazines_fashion","magazines_health","magazines_history","magazines_home","magazines_literary","magazines_men","magazines_movies_and_music","magazines_politics","magazines_outdoors","magazines_family","magazines_pets","magazines_professional","magazines_regional","magazines_science","magazines_sports","magazines_teens","magazines_travel","magazines_women","medical","music","navigation","news","photo_and_video","productivity","reference","shopping","social_networking","sports","travel","utilities","weather"]},"example":"photo_and_video"},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of apps to retrieve (default 100, max 500).","schema":{"type":"integer"},"example":100},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical app wrappers ({ app })","items":{"type":"object","description":"Canonical app wrapper","properties":{"app":{"type":"object","description":"Canonical App object (unified across app marketplaces)","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/app-listings-search":{"get":{"summary":"Search the Apple App Store listings database (paginated)","description":"Searches DataForSEO's real-time, filterable Apple App Store listings database by app title (and/or description) and returns a unified AppList. Unlike the store-chart endpoints this one is the ONE true paginator — page with `limit` (≤50) + `offset` (then `offset_token` for deeper) and read the platform-wide `total`. Premium-tier because the upstream bills per returned item. Sourced from DataForSEO's synchronous live App Data database.","tags":["app_store"],"operationId":"get_app_store_app_listings_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"title","in":"query","required":true,"description":"App title to search for (e.g. 'photo editor').","schema":{"type":"string"},"example":"photo editor"},{"name":"description","in":"query","required":false,"description":"Optional app-description text to match.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Apps per page (1–50, default 20).","schema":{"type":"integer"},"example":20},{"name":"offset","in":"query","required":false,"description":"Pagination offset (up to 10,000; use offset_token beyond).","schema":{"type":"integer"}},{"name":"offset_token","in":"query","required":false,"description":"Opaque deep-pagination cursor from a prior response.","schema":{"type":"string"}},{"name":"filters","in":"query","required":false,"description":"Advanced DataForSEO filter expression as a JSON array.","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"Storefront country as a DFS location name or numeric code. Defaults to the US.","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en'). Defaults to 'en'.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical app wrappers ({ app })","items":{"type":"object","description":"Canonical app wrapper","properties":{"app":{"type":"object","description":"Canonical App object (unified across app marketplaces)","properties":{"id":{"type":"string","description":"Store app ID (Google Play package name / App Store numeric id)"},"store":{"type":"string","description":"App marketplace (\"google_play\" or \"app_store\")"},"url":{"type":["string","null"],"description":"String at app.url"},"title":{"type":["string","null"],"description":"App title"},"icon":{"type":["string","null"],"description":"String at app.icon"},"description":{"type":["string","null"],"description":"String at app.description"},"developer":{"type":"object","description":"Developer block (name, id, url; email/address for Google)","properties":{"id":{"type":["string","null"],"description":"String at app.developer.id"},"name":{"type":["string","null"],"description":"String at app.developer.name"},"url":{"type":["string","null"],"description":"String at app.developer.url"},"email":{"type":["string","null"],"description":"String at app.developer.email"},"address":{"type":["string","null"],"description":"String at app.developer.address"},"website":{"type":["string","null"],"description":"String at app.developer.website"}}},"rating":{"type":"object","description":"Aggregate rating (value, max, number of ratings)","properties":{"value":{"type":["integer","null"],"description":"Numeric at app.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at app.rating.max"},"count":{"type":["integer","null"],"description":"Numeric at app.rating.count"}}},"price":{"type":"object","description":"Price block (current, original, currency, is_free, displayed)","properties":{"current":{"type":["integer","null"],"description":"Numeric at app.price.current"},"original":{"type":["integer","null"],"description":"Numeric at app.price.original"},"currency":{"type":["string","null"],"description":"String at app.price.currency"},"is_free":{"type":["boolean","null"],"description":"Boolean at app.price.is_free"},"displayed":{"type":["string","null"],"description":"String at app.price.displayed"}}},"reviews_count":{"type":["integer","null"],"description":"Numeric at app.reviews_count"},"category":{"type":["string","null"],"description":"String at app.category"},"categories":{"type":["array","null"],"description":"Array at app.categories","items":{"type":"string","description":"String at app.categories"}},"installs":{"type":["object","null"],"description":"Install signal (Google only): { display \"1,000,000,000+\", count }; null on Apple","properties":{"display":{"type":["string","null"],"description":"String at app.installs.display"},"count":{"type":["integer","null"],"description":"Numeric at app.installs.count"}}},"version":{"type":["string","null"],"description":"String at app.version"},"minimum_os_version":{"type":["string","null"],"description":"String at app.minimum_os_version"},"size":{"type":["string","null"],"description":"String at app.size"},"released_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"updated_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"update_notes":{"type":["string","null"],"description":"String at app.update_notes"},"image_urls":{"type":["array","null"],"description":"Screenshot URLs","items":{"type":"string","description":"Screenshot URLs"}},"video_urls":{"type":["array","null"],"description":"Array at app.video_urls","items":{"type":"string","description":"String at app.video_urls"}},"languages":{"type":["array","null"],"description":"Array at app.languages","items":{"type":"string","description":"String at app.languages"}},"advisories":{"type":["array","null"],"description":"Apple age/content advisories (null on Google)","items":{"type":"string","description":"Apple age/content advisories (null on Google)"}},"genres":{"type":["array","null"],"description":"Google Play genres (null on Apple)","items":{"type":"string","description":"Google Play genres (null on Apple)"}},"tags":{"type":["array","null"],"description":"Array at app.tags","items":{"type":"string","description":"String at app.tags"}},"similar_apps":{"type":["array","null"],"description":"Array at app.similar_apps","items":{"type":"object","description":"Nested object: app.similar_apps","properties":{"id":{"type":["string","null"],"description":"String at app.similar_apps.id"},"title":{"type":["string","null"],"description":"String at app.similar_apps.title"},"url":{"type":["string","null"],"description":"String at app.similar_apps.url"}}}},"more_by_developer":{"type":["array","null"],"description":"Array at app.more_by_developer","items":{"type":"object","description":"Nested object: app.more_by_developer","properties":{"id":{"type":["string","null"],"description":"String at app.more_by_developer.id"},"title":{"type":["string","null"],"description":"String at app.more_by_developer.title"},"url":{"type":["string","null"],"description":"String at app.more_by_developer.url"}}}},"ext":{"type":["object","null"],"description":"Nested object: app.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at app.ext.appdata"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/categories":{"get":{"summary":"List Apple App Store app categories","description":"Returns the list of Apple App Store app categories used by the `app_category` filter on /v1/app_store/app-list. Static reference data — heavily cached.","tags":["app_store"],"operationId":"get_app_store_categories","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/locations":{"get":{"summary":"List supported Apple App Store storefront locations","description":"Returns the locations (name + numeric location code) supported by the Apple App Store App Data endpoints. Use a code or name as the `country` param. Static reference data — heavily cached.","tags":["app_store"],"operationId":"get_app_store_locations","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/app_store/languages":{"get":{"summary":"List supported Apple App Store languages","description":"Returns the languages (name + code) supported by the Apple App Store App Data endpoints. Use a code as the `language` param. Static reference data — heavily cached.","tags":["app_store"],"operationId":"get_app_store_languages","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tripadvisor/search":{"get":{"summary":"Search TripAdvisor businesses & places","description":"Searches TripAdvisor for businesses and places (restaurants, hotels, attractions) matching a keyword in a location. Returns a unified PlaceList — each result carries the place name, category, star rating, total review count, and the `url_path` (the `id`/`url` are derived from it) that you pass to /v1/tripadvisor/reviews to pull that place's reviews. Results are location-bound (default: United States). Sourced from DataForSEO's task-based Business Data API; the async lifecycle is handled server-side, so this is an ordinary synchronous request (first calls take ~15-45s, then serve from cache).","tags":["tripadvisor"],"operationId":"get_tripadvisor_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"q","in":"query","required":true,"description":"Business category, company name, or prominent place (e.g. 'pizza restaurant').","schema":{"type":"string"},"example":"pizza restaurant"},{"name":"location","in":"query","required":false,"description":"Full location name (e.g. 'New York,New York,United States'). Default: United States. Results are location-bound.","schema":{"type":"string"},"example":"New York,New York,United States"},{"name":"language","in":"query","required":false,"description":"Optional language code to narrow results, e.g. 'en'.","schema":{"type":"string"}},{"name":"depth","in":"query","required":false,"description":"Number of results to retrieve (multiples of 30, default 30, max 60 on this synchronous endpoint).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical place wrappers ({ place })","items":{"type":"object","description":"Canonical place wrapper","properties":{"place":{"type":"object","description":"Canonical Place object (physical/local business or hotel)","properties":{"id":{"type":"string","description":"Place ID (Google cid for a business, hotel_identifier for a hotel)"},"name":{"type":["string","null"],"description":"Business / hotel name"},"url":{"type":["string","null"],"description":"Website or canonical URL"},"category":{"type":["string","null"],"description":"Primary category (e.g. \"Coffee shop\", \"Hotel\")"},"rating":{"type":"object","description":"Aggregate rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at place.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at place.rating.max"}}},"reviews_count":{"type":["integer","null"],"description":"Number of ratings"},"price_level":{"type":["string","null"],"description":"Price band (\"inexpensive\" / \"$$\" / null)"},"address":{"type":["string","null"],"description":"String at place.address"},"phone":{"type":["string","null"],"description":"String at place.phone"},"latitude":{"type":["integer","null"],"description":"Numeric at place.latitude"},"longitude":{"type":["integer","null"],"description":"Numeric at place.longitude"},"verified":{"type":["boolean","null"],"description":"Claimed-business flag (Google is_claimed)"},"description":{"type":["string","null"],"description":"String at place.description"},"image_urls":{"type":["string","array","null"],"description":"Union: string | array | null","items":{"type":"string","description":"String at place.image_urls"}},"categories":{"type":["array","null"],"description":"Array at place.categories","items":{"type":"string","description":"String at place.categories"}},"hotel":{"type":["object","null"],"description":"Hotel-only richness (stars, amenities, review topics, prices); null for plain places","properties":{"stars":{"type":["integer","null"],"description":"Numeric at place.hotel.stars"},"stars_description":{"type":["string","null"],"description":"String at place.hotel.stars_description"},"check_in_time":{"type":["string","null"],"description":"String at place.hotel.check_in_time"},"check_out_time":{"type":["string","null"],"description":"String at place.hotel.check_out_time"},"amenities":{"type":["array","null"],"description":"Array at place.hotel.amenities","items":{"type":"object","description":"Nested object: place.hotel.amenities","properties":{"category":{"type":["string","null"],"description":"String at place.hotel.amenities.category"},"name":{"type":["string","null"],"description":"String at place.hotel.amenities.name"},"available":{"type":["boolean","null"],"description":"Boolean at place.hotel.amenities.available"},"hint":{"type":["string","null"],"description":"String at place.hotel.amenities.hint"}}}},"review_topics":{"type":["array","null"],"description":"Array at place.hotel.review_topics","items":{"type":"object","description":"Nested object: place.hotel.review_topics","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.review_topics.title"},"positive_score":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_score"},"positive_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.positive_count"},"negative_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.negative_count"},"total_count":{"type":["integer","null"],"description":"Numeric at place.hotel.review_topics.total_count"}}}},"prices":{"type":["array","null"],"description":"Array at place.hotel.prices","items":{"type":"object","description":"Nested object: place.hotel.prices","properties":{"title":{"type":["string","null"],"description":"String at place.hotel.prices.title"},"price":{"type":["integer","null"],"description":"Numeric at place.hotel.prices.price"},"currency":{"type":["string","null"],"description":"String at place.hotel.prices.currency"},"url":{"type":["string","null"],"description":"String at place.hotel.prices.url"},"official_site":{"type":["boolean","null"],"description":"Boolean at place.hotel.prices.official_site"}}}}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tripadvisor/reviews":{"get":{"summary":"Get TripAdvisor reviews for a place","description":"Returns a unified ReviewList of traveler reviews for a TripAdvisor place, keyed by its `url_path` (`entity_id` on every review). Each review carries the star rating, full text, title, reviewer profile, attached photos, owner/management `responses[]`, the original + translated language (TripAdvisor auto-translates — a `translated` flag marks it), and publish date. Get the `url_path` from /v1/tripadvisor/search. Filter by traveler rating, traveler type, or a keyword. The synchronous endpoint caps `depth` at 30 (deeper history is a future async surface); a place with no matching reviews returns 404 (auto-refunded). Sourced from DataForSEO's task-based Business Data API (first calls ~15-45s, then cached).","tags":["tripadvisor"],"operationId":"get_tripadvisor_reviews","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url_path","in":"query","required":true,"description":"The TripAdvisor `url_path` of the place (from a search result), e.g. 'Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html'.","schema":{"type":"string"},"example":"Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html"},{"name":"depth","in":"query","required":false,"description":"Number of reviews to retrieve (multiples of 10, default 10, max 30 on this synchronous endpoint).","schema":{"type":"integer"},"example":10},{"name":"sort_by","in":"query","required":false,"description":"Review ordering: `most_recent` or `detailed_reviews`.","schema":{"type":"string","enum":["most_recent","detailed_reviews"]}},{"name":"rating","in":"query","required":false,"description":"Filter by traveler rating bucket: excellent | very_good | average | poor | terrible.","schema":{"type":"string","enum":["excellent","very_good","average","poor","terrible"]}},{"name":"visit_type","in":"query","required":false,"description":"Filter by traveler type: families | couples | solo | business | friends.","schema":{"type":"string","enum":["families","couples","solo","business","friends"]}},{"name":"search_reviews_keyword","in":"query","required":false,"description":"Only return reviews containing this keyword.","schema":{"type":"string"}},{"name":"translate","in":"query","required":false,"description":"Translate reviews to the place's domain language (default true). The `translated` flag + `original_language` are always returned.","schema":{"type":"boolean"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical review wrappers ({ review })","items":{"type":"object","description":"Canonical review wrapper","properties":{"review":{"type":"object","description":"Canonical Review object (shared across commerce platforms)","properties":{"id":{"type":"string","description":"Review ID (parsed from the review URL when not first-class)"},"entity_id":{"type":["string","null"],"description":"ID of the reviewed entity (e.g. the Amazon ASIN)"},"url":{"type":["string","null"],"description":"String at review.url"},"title":{"type":["string","null"],"description":"String at review.title"},"text":{"type":["string","null"],"description":"Full review body"},"rating":{"type":"object","description":"Star rating (value + max)","properties":{"value":{"type":["integer","null"],"description":"Numeric at review.rating.value"},"max":{"type":["integer","null"],"description":"Numeric at review.rating.max"}}},"author":{"type":"object","description":"Nested object: review.author","properties":{"name":{"type":["string","null"],"description":"String at review.author.name"},"avatar_url":{"type":["string","null"],"description":"String at review.author.avatar_url"},"url":{"type":["string","null"],"description":"String at review.author.url"},"location":{"type":["string","null"],"description":"String at review.author.location"},"reviews_count":{"type":["integer","null"],"description":"Numeric at review.author.reviews_count"}}},"helpful_votes":{"type":["integer","null"],"description":"Helpful-vote count (Amazon; null elsewhere)"},"verified":{"type":["boolean","null"],"description":"Verified-purchase flag (Amazon; null elsewhere)"},"source":{"type":["string","null"],"description":"String at review.source"},"language":{"type":["string","null"],"description":"String at review.language"},"original_language":{"type":["string","null"],"description":"String at review.original_language"},"translated":{"type":["boolean","null"],"description":"Boolean at review.translated"},"images":{"type":["array","null"],"description":"Array at review.images","items":{"type":"string","description":"String at review.images"}},"responses":{"type":["array","null"],"description":"Array at review.responses","items":{"type":"object","description":"Nested object: review.responses","properties":{"id":{"type":["string","null"],"description":"String at review.responses.id"},"author":{"type":["string","null"],"description":"String at review.responses.author"},"text":{"type":["string","null"],"description":"String at review.responses.text"},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"}}}},"published_at":{"type":["string","integer","null"],"description":"Union: string | integer | null"},"ext":{"type":["object","null"],"description":"Nested object: review.ext","properties":{"appdata":{"type":["string","null"],"description":"Leaf at review.ext.appdata"},"tiktokshop":{"type":["string","null"],"description":"Leaf at review.ext.tiktokshop"}}}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/utility/age-gender":{"get":{"summary":"Detect age and gender","description":"Uses AI to detect the estimated age and gender of a person from their social profile picture. Returns an age range, gender, and confidence scores.","tags":["utility"],"operationId":"get_utility_age_gender","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Social profile URL whose avatar should be analyzed (e.g. a Twitter/X profile URL)","schema":{"type":"string"},"example":"https://twitter.com/levelsio"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linktree/page":{"get":{"summary":"Get Linktree page","description":"Returns data from a Linktree page including the user's display name, bio, avatar, and list of links with titles and URLs.","tags":["linktree"],"operationId":"get_linktree_page","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Linktree page","schema":{"type":"string"},"example":"https://linktr.ee/charlidamelio"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkbio/page":{"get":{"summary":"Get Linkbio page","description":"Returns data from a Linkbio page including display name, bio, avatar, and list of links with titles and URLs.","tags":["linkbio"],"operationId":"get_linkbio_page","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Linkbio page","schema":{"type":"string"},"example":"https://lnk.bio/example"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/linkme/page":{"get":{"summary":"Get Linkme profile","description":"Returns data from a Linkme page including display name, bio, avatar, and list of links with titles and URLs.","tags":["linkme"],"operationId":"get_linkme_page","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Linkme page","schema":{"type":"string"},"example":"https://link.me/example"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/komi/page":{"get":{"summary":"Get Komi page","description":"Returns data from a Komi page including display name, bio, avatar, and list of links with titles and URLs.","tags":["komi"],"operationId":"get_komi_page","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Komi page","schema":{"type":"string"},"example":"https://kimkardashian.komi.io/"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/pillar/page":{"get":{"summary":"Get Pillar page","description":"Returns data from a Pillar page including display name, bio, avatar, and list of links with titles and URLs.","tags":["pillar"],"operationId":"get_pillar_page","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Full URL of the Pillar page","schema":{"type":"string"},"example":"https://pillar.io/example"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/polymarket/research":{"get":{"summary":"Polymarket prediction markets — multi-query research","description":"Server-side fan-out over the Gamma API: expands the topic into up to 6 search queries (core subject + individual informative words), issues all calls in parallel, dedupes events by id, filters out unrelated matches via informative-word overlap with the topic, and ranks the remainder by topic↔title similarity. Costs 5 credits because each call hits upstream multiple times. Use this when you want a curated, on-topic feed; use /v1/polymarket/search for raw single-query lookups.","tags":["polymarket"],"operationId":"get_polymarket_research","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"query","in":"query","required":true,"description":"The research topic — free-text natural language (e.g. 'last 30 days bitcoin halving', 'kanye west tour'). Framing prefixes like 'last N days' and 'what are people saying about' are stripped automatically before expansion.","schema":{"type":"string"},"example":"trump 2028 election"},{"name":"limit","in":"query","required":false,"description":"Max results per result type on each fan-out call (events / markets / profiles). Bounds the response size. Defaults to 10.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/hackernews/search":{"get":{"summary":"Search Hacker News","description":"Searches Hacker News stories, comments, and front-page items via the Algolia HN API. Defaults to story-only results sorted by relevance. The HN Algolia index only exposes `created_at_i` for numeric filtering, so use `numericFilters` for date windows (e.g. `created_at_i>1700000000`). Returns the raw Algolia hits in `data.items[]` — each hit includes `objectID`, `title`, `url`, `author`, `points`, `num_comments`, `created_at_i`, and `_tags`.","tags":["hackernews"],"operationId":"get_hackernews_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term.","schema":{"type":"string"},"example":"claude code"},{"name":"tags","in":"query","required":false,"description":"Algolia tag filter — comma-separated. Common values: \"story\", \"comment\", \"poll\", \"show_hn\", \"ask_hn\", \"front_page\", \"author_<username>\". Defaults to \"story\".","schema":{"type":"string"}},{"name":"numericFilters","in":"query","required":false,"description":"Algolia numeric filter expression on `created_at_i` (the only filterable numeric attribute) — e.g. \"created_at_i>1700000000\". Combine with commas for AND. No filter is applied by default.","schema":{"type":"string"}},{"name":"hitsPerPage","in":"query","required":false,"description":"Hits per page (1–1000). Defaults to 30.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"0-indexed page number for pagination.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/hackernews/story":{"get":{"summary":"Get a Hacker News story","description":"Returns story metadata for a single HN item — title, url, author, points, num_comments, and published_at — mapped to the unified Post schema. The full nested comment tree is dropped from this response; use `/v1/hackernews/story/comments` to fetch the children.","tags":["hackernews"],"operationId":"get_hackernews_story","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"id","in":"query","required":true,"description":"HN story id (the numeric `objectID`).","schema":{"type":"string"},"example":"8863"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/hackernews/story/comments":{"get":{"summary":"Get comments on a Hacker News story","description":"Returns the comment tree for a story under `data.items[]` — each entry includes `id`, `author`, `text` (HTML), `points`, `created_at`, and a recursive `children` array of nested replies. Same upstream call as `/v1/hackernews/story` but the CommentList archetype tells strip-envelope to pick the `children` list.","tags":["hackernews"],"operationId":"get_hackernews_story_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"id","in":"query","required":true,"description":"HN story id (the numeric `objectID`).","schema":{"type":"string"},"example":"8863"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/hackernews/profile":{"get":{"summary":"Get a Hacker News user profile","description":"Returns public profile information for a Hacker News user — id, username, bio (`about`), karma, and account-creation date — mapped to the unified Author schema. HN has no follower / following / posts_count / verified concept, so those unified fields resolve to null.","tags":["hackernews"],"operationId":"get_hackernews_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Hacker News username (case-sensitive, e.g. `pg` or `kogir`).","schema":{"type":"string"},"example":"pg"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/profile":{"get":{"summary":"Get a GitHub user profile","description":"Returns public profile information for a GitHub user — login, name, avatar, bio, follower / following / public-repos counts, and account-creation date — mapped to the unified Author schema. `author.likes_count` surfaces `public_gists` (a creation-count analog); `author.verified` surfaces the rare `site_admin` flag (true only for GitHub staff accounts).","tags":["github"],"operationId":"get_github_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"GitHub username — 1–39 chars, alphanumeric + non-consecutive hyphens, no leading/trailing hyphen.","schema":{"type":"string"},"example":"octocat"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/repo":{"get":{"summary":"Get a GitHub repository","description":"Returns repository metadata — full_name, description, stars, forks, open issues, watchers, language, and creation date — mapped to the unified Author schema. A repo is a follow-able creator-like entity in this API: stars map to `author.followers`, watchers (subscribers) to `author.likes_count`, forks to `author.following`. Use `/v1/github/repo/readme`, `/v1/github/repo/releases`, and `/v1/github/repo/issues` for richer per-repo data.","tags":["github"],"operationId":"get_github_repo","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub repo URL — `https://github.com/{owner}/{repo}`.","schema":{"type":"string"},"example":"https://github.com/octocat/Hello-World"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/profile/repos":{"get":{"summary":"List a GitHub user's repositories","description":"Returns the public repositories owned by the user under `data.items[]` — each entry includes `id`, `name`, `full_name`, `description`, `language`, `stargazers_count`, `forks_count`, `created_at`, and `pushed_at`. Sortable by `created`, `updated`, `pushed`, or `full_name`. Use `/v1/github/repo` for a single richer repo dossier.","tags":["github"],"operationId":"get_github_profile_repos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"GitHub username.","schema":{"type":"string"},"example":"octocat"},{"name":"type","in":"query","required":false,"description":"Filter — `all`, `owner`, or `member`. Defaults to `owner`.","schema":{"type":"string","enum":["all","owner","member"]}},{"name":"sort","in":"query","required":false,"description":"Sort field — `created`, `updated`, `pushed`, or `full_name`. Defaults to `full_name`.","schema":{"type":"string","enum":["created","updated","pushed","full_name"]}},{"name":"direction","in":"query","required":false,"description":"`asc` or `desc`. Defaults to `asc` for full_name, `desc` otherwise.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"per_page","in":"query","required":false,"description":"Repos per page (1–100). Defaults to 30.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"1-indexed page number for pagination.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/repo/readme":{"get":{"summary":"Get a repository's README","description":"Returns the repository's README in raw form (the file contents, not base64-wrapped). The fetcher sets `Accept: application/vnd.github.raw+json` so the response body is the actual file. Useful for content discovery and AI-grounding workflows.","tags":["github"],"operationId":"get_github_repo_readme","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub repo URL — `https://github.com/{owner}/{repo}`.","schema":{"type":"string"},"example":"https://github.com/octocat/Hello-World"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/repo/releases":{"get":{"summary":"List a repository's releases","description":"Returns the most recent releases for the repository under `data.items[]` — each entry includes `tag_name`, `name`, `body` (markdown release notes), `published_at`, `prerelease`, and `assets[]`. Sorted newest-first by upstream default.","tags":["github"],"operationId":"get_github_repo_releases","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub repo URL — `https://github.com/{owner}/{repo}`.","schema":{"type":"string"},"example":"https://github.com/facebook/react"},{"name":"per_page","in":"query","required":false,"description":"Releases per page (1–100). Defaults to 30.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"1-indexed page number.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/repo/issues":{"get":{"summary":"List a repository's issues (and PRs)","description":"Returns issues for the repository under `data.items[]`. NOTE: GitHub treats pull requests as issues for this endpoint — every PR also appears here, distinguishable by the presence of a `pull_request` field on the item. Filter by `state`, comma-separated `labels`, sort by `created`/`updated`/`comments`, and paginate with `per_page`/`page`. `since` accepts an ISO 8601 timestamp.","tags":["github"],"operationId":"get_github_repo_issues","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub repo URL — `https://github.com/{owner}/{repo}`.","schema":{"type":"string"},"example":"https://github.com/facebook/react"},{"name":"type","in":"query","required":false,"description":"Filter the unified issues+PRs list — `issue` returns only issues, `pr` returns only pull requests, `all` (default) returns both. Each item also carries `post.ext.type` (`issue`/`pull_request`).","schema":{"type":"string","enum":["issue","pr","all"]}},{"name":"state","in":"query","required":false,"description":"`open`, `closed`, or `all`. Defaults to `open`.","schema":{"type":"string","enum":["open","closed","all"]}},{"name":"labels","in":"query","required":false,"description":"Comma-separated label names (e.g. `bug,help wanted`).","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"`created`, `updated`, or `comments`. Defaults to `created`.","schema":{"type":"string","enum":["created","updated","comments"]}},{"name":"direction","in":"query","required":false,"description":"`asc` or `desc`. Defaults to `desc`.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"since","in":"query","required":false,"description":"Only issues updated at or after this ISO 8601 timestamp.","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Issues per page (1–100). Defaults to 30.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"1-indexed page number.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/issue":{"get":{"summary":"Get a single issue or pull request","description":"Returns full metadata for an issue or PR — title, body, author, labels, state, reactions, comments count, and timestamps — mapped to the unified Post schema. Pass either an `/issues/N` or `/pull/N` URL; GitHub's API treats them interchangeably under `/issues/N`. Use `/v1/github/issue/comments` for the discussion thread.","tags":["github"],"operationId":"get_github_issue","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub HTML URL — `https://github.com/{owner}/{repo}/issues/{n}` or `/pull/{n}`.","schema":{"type":"string"},"example":"https://github.com/facebook/react/issues/27522"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/issue/comments":{"get":{"summary":"Get comments on an issue or pull request","description":"Returns comments under `data.items[]` — each entry includes `id`, `user.login`, `body`, `reactions.total_count`, and `created_at`. Pass either an `/issues/N` or `/pull/N` URL; both resolve to the same comment thread on GitHub's API. Comments are returned in ascending `created_at` order (GitHub does not support re-sorting a single issue's comments).","tags":["github"],"operationId":"get_github_issue_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub HTML URL of the issue or PR.","schema":{"type":"string"},"example":"https://github.com/facebook/react/issues/27522"},{"name":"since","in":"query","required":false,"description":"Only comments updated at or after this ISO 8601 timestamp.","schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"description":"Comments per page (1–100). Defaults to 30.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"1-indexed page number.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/search":{"get":{"summary":"Search GitHub issues and pull requests","description":"Searches issues and PRs across all of GitHub via the `/search/issues` endpoint. Supports GitHub's full search syntax — qualifiers like `repo:owner/name`, `is:issue`, `is:pr`, `is:open`, `label:bug`, `created:>2026-01-01`, `author:username`, `comments:>10`. Sort by `reactions`, `comments`, `created`, or `updated`. Results land under `data.items[]` with `total_count` and `incomplete_results` siblings. Rate-limited to 30 req/min per token.","tags":["github"],"operationId":"get_github_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"GitHub search query (uses GitHub's qualifier syntax — see https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests).","schema":{"type":"string"},"example":"repo:vercel/next.js is:issue is:open"},{"name":"sort","in":"query","required":false,"description":"Sort field — `reactions`, `comments`, `created`, `updated`. Defaults to best-match relevance.","schema":{"type":"string","enum":["reactions","comments","created","updated"]}},{"name":"order","in":"query","required":false,"description":"`asc` or `desc`. Defaults to `desc`.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"per_page","in":"query","required":false,"description":"Results per page (1–100). Defaults to 30.","schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"description":"1-indexed page number.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/repo/top-issues":{"get":{"summary":"Top feature request and top complaint for a repository","description":"Composite endpoint — runs two `/search/issues` queries in parallel: `top_feature_request` (issues with `enhancement` label, sorted by reactions; falls back to top open issue by reactions if no label exists) and `top_complaint` (most-discussed open issue, sorted by comments). Returns `{ top_feature_request, top_complaint }`. 5 credits per call.","tags":["github"],"operationId":"get_github_repo_top_issues","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub repo URL — `https://github.com/{owner}/{repo}`.","schema":{"type":"string"},"example":"https://github.com/facebook/react"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/repo/dossier":{"get":{"summary":"Full project dossier for a repository","description":"Composite endpoint — fetches repo metadata, README excerpt, latest 3 releases, top feature request, and top complaint in parallel and returns a structured dossier `{ info, readme, releases, top_issues }`. Useful for AI-grounding workflows where a single call should return everything you'd need to summarise a project. 5 credits per call.","tags":["github"],"operationId":"get_github_repo_dossier","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"advanced","x-credit-cost":5,"parameters":[{"name":"url","in":"query","required":true,"description":"GitHub repo URL — `https://github.com/{owner}/{repo}`.","schema":{"type":"string"},"example":"https://github.com/facebook/react"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/github/user/profile-velocity":{"get":{"summary":"User contribution velocity dossier","description":"Composite endpoint — combines a `/search/issues` PR-velocity query (total + merged), the user's own repo list, and parallel per-repo enrichment (stars + releases for external repos; README + releases + top-issues for own repos) into a structured contribution dossier `{ velocity, contributed_repos[], own_repos[] }`. The `depth` param controls fan-out width: `quick` enriches up to 5 external + 3 own repos, `default` 10 + 5, `deep` 15 + 5. 10 credits per call.","tags":["github"],"operationId":"get_github_user_profile_velocity","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"handle","in":"query","required":true,"description":"GitHub username.","schema":{"type":"string"},"example":"octocat"},{"name":"depth","in":"query","required":false,"description":"`quick`, `default`, or `deep`. Defaults to `default`. Trades off upstream calls vs. dossier richness.","schema":{"type":"string","enum":["quick","default","deep"]}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tavily/search":{"get":{"summary":"Tavily web search with optional LLM-generated answer","description":"Runs a web search via Tavily and returns ranked results plus an optional LLM-generated `answer` synthesised from the top sources. Set `include_answer=true` to enable answer synthesis. Use `search_depth=advanced` for higher-relevance results (also unlocks `chunks_per_source`). Filter results to specific domains via `include_domains` (comma-separated), or exclude via `exclude_domains`. Time-bounded queries via `time_range` (`d` / `w` / `m` / `y`) or explicit `start_date` / `end_date` (YYYY-MM-DD).","tags":["tavily"],"operationId":"get_tavily_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"The search query — natural-language free text.","schema":{"type":"string"},"example":"claude opus 4.7 release notes"},{"name":"search_depth","in":"query","required":false,"description":"Latency-vs-relevance tradeoff. `basic` is the default; `advanced` unlocks `chunks_per_source` and higher-relevance ranking.","schema":{"type":"string","enum":["basic","advanced","fast","ultra-fast"]}},{"name":"topic","in":"query","required":false,"description":"Search category. Defaults to `general`. Use `news` for time-sensitive queries and `finance` for market data.","schema":{"type":"string","enum":["general","news","finance"]}},{"name":"time_range","in":"query","required":false,"description":"Time window relative to now. Accepts `day` / `week` / `month` / `year` (or shorthand `d` / `w` / `m` / `y`).","schema":{"type":"string","enum":["day","week","month","year","d","w","m","y"]}},{"name":"max_results","in":"query","required":false,"description":"Number of results to return (1–20). Defaults to 5.","schema":{"type":"integer"}},{"name":"chunks_per_source","in":"query","required":false,"description":"Max relevant chunks returned per source (1–5). Only honoured when `search_depth=advanced`. Defaults to 3.","schema":{"type":"integer"}},{"name":"include_images","in":"query","required":false,"description":"Include images alongside the result content.","schema":{"type":"boolean"}},{"name":"include_image_descriptions","in":"query","required":false,"description":"Include AI-generated descriptions for the returned images.","schema":{"type":"boolean"}},{"name":"include_answer","in":"query","required":false,"description":"Include an LLM-generated answer string synthesised from the top sources.","schema":{"type":"boolean"}},{"name":"include_raw_content","in":"query","required":false,"description":"Include the raw HTML/text alongside the cleaned content.","schema":{"type":"boolean"}},{"name":"include_domains","in":"query","required":false,"description":"Comma-separated list of domains to restrict results to (e.g. `nytimes.com,reuters.com`).","schema":{"type":"string"}},{"name":"exclude_domains","in":"query","required":false,"description":"Comma-separated list of domains to exclude from results.","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code to bias results toward.","schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"description":"Inclusive lower bound on result publish date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"Inclusive upper bound on result publish date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tavily/extract":{"get":{"summary":"Extract clean content from one or more URLs","description":"Pulls clean, AI-ready text out of one or more URLs via Tavily's extractor. Pass a single URL or a comma-separated list (max 20). Returns extracted content per URL alongside any URLs that failed extraction. Use `extract_depth=advanced` for harder pages (paywalls, JS-heavy SPAs).","tags":["tavily"],"operationId":"get_tavily_extract","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"urls","in":"query","required":true,"description":"Comma-separated list of URLs to extract (max 20).","schema":{"type":"string"},"example":"https://en.wikipedia.org/wiki/Lionel_Messi"},{"name":"extract_depth","in":"query","required":false,"description":"Extraction strategy. `basic` is the default and faster; `advanced` handles harder pages but takes longer.","schema":{"type":"string","enum":["basic","advanced"]}},{"name":"format","in":"query","required":false,"description":"Output format for the extracted content. `markdown` (default) preserves structure; `text` is plain.","schema":{"type":"string","enum":["markdown","text"]}},{"name":"include_images","in":"query","required":false,"description":"Include images extracted from each URL.","schema":{"type":"boolean"}},{"name":"include_favicon","in":"query","required":false,"description":"Include the favicon URL for each page.","schema":{"type":"boolean"}},{"name":"timeout","in":"query","required":false,"description":"Per-URL timeout in seconds (1–60).","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tavily/map":{"get":{"summary":"Map a website's sitegraph","description":"Returns the sitegraph of a website starting from a root URL — a list of discovered URLs without their full content. Cheaper and faster than crawl when you only need to enumerate pages (e.g. for sitemap discovery or coverage analysis). Use `instructions` to guide the mapper in natural language and the `select_*` / `exclude_*` filters (regex patterns, comma-separated) to narrow scope.","tags":["tavily"],"operationId":"get_tavily_map","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Root URL to begin mapping.","schema":{"type":"string"},"example":"https://docs.tavily.com"},{"name":"max_depth","in":"query","required":false,"description":"Maximum link depth from the root URL. Defaults to 1.","schema":{"type":"integer"}},{"name":"max_breadth","in":"query","required":false,"description":"Maximum number of links followed per level (per page). Defaults to 20.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Total number of links the mapper will process before stopping. Defaults to 50.","schema":{"type":"integer"}},{"name":"instructions","in":"query","required":false,"description":"Natural-language instructions for the mapper (e.g. 'Find all pages related to API documentation').","schema":{"type":"string"}},{"name":"select_paths","in":"query","required":false,"description":"Comma-separated regex patterns — only include URLs whose path matches.","schema":{"type":"string"}},{"name":"select_domains","in":"query","required":false,"description":"Comma-separated regex patterns — only include URLs whose domain matches.","schema":{"type":"string"}},{"name":"exclude_paths","in":"query","required":false,"description":"Comma-separated regex patterns — exclude URLs whose path matches.","schema":{"type":"string"}},{"name":"exclude_domains","in":"query","required":false,"description":"Comma-separated regex patterns — exclude URLs whose domain matches.","schema":{"type":"string"}},{"name":"allow_external","in":"query","required":false,"description":"Whether to follow / return links to external domains. Defaults to true.","schema":{"type":"boolean"}},{"name":"timeout","in":"query","required":false,"description":"Maximum time in seconds (10–150).","schema":{"type":"integer"}},{"name":"categories","in":"query","required":false,"description":"Comma-separated list of category hints to bias mapping toward.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/tavily/crawl":{"get":{"summary":"Crawl a website with LLM-driven path selection","description":"Multi-page crawl starting from a root URL. Returns each crawled page with its extracted content (unlike map, which returns only URLs). Use `instructions` to guide the crawler in natural language — Tavily uses an LLM to follow only the paths matching your intent. Use `select_*` / `exclude_*` filters (comma-separated regex patterns) to constrain scope.","tags":["tavily"],"operationId":"get_tavily_crawl","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Root URL to begin crawling.","schema":{"type":"string"},"example":"https://docs.tavily.com"},{"name":"max_depth","in":"query","required":false,"description":"Maximum link depth from the root URL. Defaults to 1.","schema":{"type":"integer"}},{"name":"max_breadth","in":"query","required":false,"description":"Maximum number of links followed per level (per page). Defaults to 20.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Total number of pages the crawler will process before stopping. Defaults to 50.","schema":{"type":"integer"}},{"name":"instructions","in":"query","required":false,"description":"Natural-language instructions for the crawler (e.g. 'Find all product pages with pricing').","schema":{"type":"string"}},{"name":"select_paths","in":"query","required":false,"description":"Comma-separated regex patterns — only crawl URLs whose path matches.","schema":{"type":"string"}},{"name":"select_domains","in":"query","required":false,"description":"Comma-separated regex patterns — only crawl URLs whose domain matches.","schema":{"type":"string"}},{"name":"exclude_paths","in":"query","required":false,"description":"Comma-separated regex patterns — skip URLs whose path matches.","schema":{"type":"string"}},{"name":"exclude_domains","in":"query","required":false,"description":"Comma-separated regex patterns — skip URLs whose domain matches.","schema":{"type":"string"}},{"name":"allow_external","in":"query","required":false,"description":"Whether to follow links to external domains. Defaults to true.","schema":{"type":"boolean"}},{"name":"extract_depth","in":"query","required":false,"description":"Per-page extraction strategy. `basic` is faster; `advanced` handles harder pages.","schema":{"type":"string","enum":["basic","advanced"]}},{"name":"format","in":"query","required":false,"description":"Output format for extracted content. `markdown` (default) or `text`.","schema":{"type":"string","enum":["markdown","text"]}},{"name":"categories","in":"query","required":false,"description":"Comma-separated list of category hints to bias the crawl toward.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"metrics":{"type":"object","description":"Key performance metrics","properties":{"total_views":{"type":"integer","description":"Total view count"},"total_likes":{"type":"integer","description":"Total like count"},"total_comments":{"type":"integer","description":"Total comment count"},"engagement_rate":{"type":"number","description":"Computed engagement rate (0-1)"}}},"period":{"type":["string","null"],"description":"Time period for the analytics data"},"breakdown":{"type":["array","null"],"description":"Per-item or per-period breakdown","items":{"type":"object","description":"Breakdown entry"}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"instagram","endpoint":"/v1/instagram/engagement","data":{"engagement_rate_percentages":38.33,"recent_posts":12,"followers":87608035,"comments":528912,"likes":33049046,"recent_posts_explanation":"Statistics based on the last 12 posts","id_user":"2278169415","username":"mrbeast","is_private":false,"posts_details":[{"likes":5636982,"comments":69484,"taken_at":1781457954,"datetime":"2026-06-14 20:25:54","hours_since_post":461,"time_ago":"19 days ago","likes_per_hour":12228,"comments_per_hour":151},{"likes":20000768,"comments":223510,"taken_at":1732824650,"datetime":"2024-11-28 23:10:50","hours_since_post":13971,"time_ago":"2 years ago","likes_per_hour":1432,"comments_per_hour":16},{"likes":929226,"comments":30633,"taken_at":1782232475,"datetime":"2026-06-23 19:34:35","hours_since_post":246,"time_ago":"10 days ago","likes_per_hour":3777,"comments_per_hour":125},{"likes":487761,"comments":22482,"taken_at":1781799425,"datetime":"2026-06-18 19:17:05","hours_since_post":366,"time_ago":"15 days ago","likes_per_hour":1333,"comments_per_hour":61},{"likes":712265,"comments":15716,"taken_at":1781366405,"datetime":"2026-06-13 19:00:05","hours_since_post":487,"time_ago":"20 days ago","likes_per_hour":1463,"comments_per_hour":32},{"likes":1475116,"comments":35386,"taken_at":1781277094,"datetime":"2026-06-12 18:11:34","hours_since_post":512,"time_ago":"21 days ago","likes_per_hour":2881,"comments_per_hour":69},{"likes":1108220,"comments":26632,"taken_at":1780160249,"datetime":"2026-05-30 19:57:29","hours_since_post":822,"time_ago":"1 months ago","likes_per_hour":1348,"comments_per_hour":32},{"likes":542948,"comments":28476,"taken_at":1779375582,"datetime":"2026-05-21 17:59:42","hours_since_post":1040,"time_ago":"1 months ago","likes_per_hour":522,"comments_per_hour":27},{"likes":698514,"comments":24401,"taken_at":1779120014,"datetime":"2026-05-18 19:00:14","hours_since_post":1111,"time_ago":"2 months ago","likes_per_hour":629,"comments_per_hour":22},{"likes":468000,"comments":13548,"taken_at":1778947209,"datetime":"2026-05-16 19:00:09","hours_since_post":1159,"time_ago":"2 months ago","likes_per_hour":404,"comments_per_hour":12},{"likes":526594,"comments":24411,"taken_at":1777737719,"datetime":"2026-05-02 19:01:59","hours_since_post":1495,"time_ago":"2 months ago","likes_per_hour":352,"comments_per_hour":16},{"likes":462652,"comments":14233,"taken_at":1777580305,"datetime":"2026-04-30 23:18:25","hours_since_post":1538,"time_ago":"2 months ago","likes_per_hour":301,"comments_per_hour":9}]},"credits_used":5,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/blog/search":{"get":{"summary":"Search Naver Blog","description":"Searches naver.com/blog — Korea's dominant long-form blogging platform. Returns ranked posts under `data.items[]` with `title`, `link`, `description` (both HTML-tagged with `<b>` around matched keywords), `bloggername`, `bloggerlink`, and `postdate` (YYYYMMDD).","tags":["naver"],"operationId":"get_naver_blog_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"소셜크롤"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/news/search":{"get":{"summary":"Search Naver News","description":"Searches news.naver.com — aggregated Korean news from licensed publishers. Returns articles under `data.items[]` with `title`, `originallink` (publisher URL), `link` (naver-hosted URL), `description`, and `pubDate` (RFC 1123).","tags":["naver"],"operationId":"get_naver_news_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"삼성전자"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/book/search":{"get":{"summary":"Search Naver Book","description":"Searches book.naver.com — book metadata catalog. Returns books under `data.items[]` with `title`, `link`, `image` (cover URL), `author`, `discount` (price after discount, KRW), `publisher`, `pubdate` (YYYYMMDD), `isbn`, and `description`.","tags":["naver"],"operationId":"get_naver_book_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"데미안"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: sim|date|asc|dsc (asc/dsc = price asc/desc). Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/encyc/search":{"get":{"summary":"Search Naver Encyclopedia","description":"Searches terms.naver.com — Naver Knowledge Encyclopedia, a curated reference corpus aggregating dictionaries, technical references, and editorial knowledge entries. Returns entries under `data.items[]` with `title`, `link`, `description`, and `thumbnail`.","tags":["naver"],"operationId":"get_naver_encyc_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"양자역학"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/cafearticle/search":{"get":{"summary":"Search Naver Cafe articles","description":"Searches cafe.naver.com — Korea's largest user-community platform (analog of Reddit subreddits / Discord servers). Returns cafe posts under `data.items[]` with `title`, `link`, `description`, `cafename`, and `cafeurl`. Many cafes are member-gated; the `link` URL works only if the caller has joined the cafe (Naver returns a teaser otherwise).","tags":["naver"],"operationId":"get_naver_cafearticle_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"주식"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/kin/search":{"get":{"summary":"Search Naver KnowledgeiN (지식iN)","description":"Searches kin.naver.com — Korea's dominant Q&A community (analog of StackOverflow + Quora for the general public). Returns Q&A threads under `data.items[]` with `title`, `link`, and `description` (typically a question or answer excerpt).","tags":["naver"],"operationId":"get_naver_kin_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"코로나 증상"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: sim|date|point. Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/local/search":{"get":{"summary":"Search Naver Local (장소 검색)","description":"Searches map.naver.com places — Korean business / point-of-interest catalog. Returns places under `data.items[]` with `title`, `link`, `category`, `description`, `telephone`, `address` (legal-district), `roadAddress` (street), `mapx` / `mapy` (KATEC coordinates). Note: `display` is capped at 5 and `start` at 1 for this corpus — Naver returns HTTP 400 above those bounds.","tags":["naver"],"operationId":"get_naver_local_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"강남역 카페"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: random|comment (display max 5, start max 1). Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/shop/search":{"get":{"summary":"Search Naver Shopping","description":"Searches shopping.naver.com — Naver's price-comparison shopping aggregator (analog of Google Shopping for the Korean market). Returns products under `data.items[]` with `title`, `link`, `image`, `lprice` (low price, KRW), `hprice` (high price), `mallName` (merchant), `productId`, `productType`, `brand`, `maker`, and four `category` levels.","tags":["naver"],"operationId":"get_naver_shop_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"노트북"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: sim|date|asc|dsc (asc/dsc = price asc/desc). Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/doc/search":{"get":{"summary":"Search Naver Academic Documents (전문자료)","description":"Searches academic.naver.com — Korean academic paper / report / public-document corpus (theses, journal articles, government reports). Returns documents under `data.items[]` with `title`, `link`, and `description`.","tags":["naver"],"operationId":"get_naver_doc_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"딥러닝"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/image/search":{"get":{"summary":"Search Naver Image","description":"Searches Naver Image — image search across crawled Korean web. Returns images under `data.items[]` with `title`, `link` (image URL), `thumbnail` (preview URL), `sizeheight`, and `sizewidth`.","tags":["naver"],"operationId":"get_naver_image_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"한라산"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: sim|date. Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/naver/webkr/search":{"get":{"summary":"Search Naver Web (웹문서)","description":"Searches Naver web index — general Korean web search (analog of Google web search, scoped to Naver's crawl of the Korean-language web). Returns pages under `data.items[]` with `title`, `link`, and `description`.","tags":["naver"],"operationId":"get_naver_webkr_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Free-text search term (UTF-8). Required.","schema":{"type":"string"},"example":"기후변화"},{"name":"display","in":"query","required":false,"description":"Number of items to return per page. Defaults to 10. Standard cap 100 (local corpus caps at 5).","schema":{"type":"integer"},"example":10},{"name":"start","in":"query","required":false,"description":"1-indexed offset for pagination. Defaults to 1. Standard cap 1000 (local corpus caps at 1).","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Accepted values: (sort ignored). Defaults to `sim` (relevance) when the corpus supports sort.","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/rumble/search":{"get":{"summary":"Search Rumble videos","description":"Searches Rumble videos by keyword. Returns matching videos and shorts with title, URL, thumbnail, channel, published date, view-count text + integer, plus a numeric cursor for the next page.","tags":["rumble"],"operationId":"get_rumble_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search query.","schema":{"type":"string"},"example":"funny cats"},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous response — the next page number (e.g. `2`).","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/rumble/channel/videos":{"get":{"summary":"List videos for a Rumble channel","description":"Returns channel metadata, videos, shorts, and a numeric cursor for the next page. Pass either `handle` or `url`.","tags":["rumble"],"operationId":"get_rumble_channel_videos","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["handle","url"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Rumble channel handle. (one of: handle, url — at least one required)","schema":{"type":"string"},"example":"CuteCats223"},{"name":"url","in":"query","required":false,"description":"Rumble channel URL. (one of: handle, url — at least one required)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous response — the next page number (e.g. `2`).","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/rumble/video":{"get":{"summary":"Get a Rumble video","description":"Returns title, description, thumbnail, channel, publish date, view count, likes, dislikes, captions, and media metadata when available.","tags":["rumble"],"operationId":"get_rumble_video","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Rumble video URL.","schema":{"type":"string"},"example":"https://rumble.com/v79xhhm-discovery-example.html"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/rumble/video/transcript":{"get":{"summary":"Get a Rumble video transcript","description":"Returns the transcript for a Rumble video when captions are available. If Rumble doesn't expose captions, `transcript` is `null` and credits are not deducted.","tags":["rumble"],"operationId":"get_rumble_video_transcript","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"premium","x-credit-cost":10,"parameters":[{"name":"url","in":"query","required":true,"description":"Rumble video URL.","schema":{"type":"string"},"example":"https://rumble.com/v784xoi-president-donald-j.-trump-and-secwar-pete-hegseth-hold-a-press-conference-a.html"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"transcript":{"type":["string","null"],"description":"Full transcript text. Plain string for TikTok/Facebook/Twitter; see `transcripts` for Instagram and the segmented YouTube shape."},"transcripts":{"type":["array","null"],"description":"Instagram transcript entries. Each item has a `text` field with the full transcript for that track.","items":{"type":"object","description":"Transcript track","properties":{"text":{"type":"string","description":"Transcript text"}}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/post/transcript","data":{"id":"7499229683859426602","url":"https://www.tiktok.com/@stoolpresidente/video/7499229683859426602","transcript":"WEBVTT\n\n\n00:00:00.180 --> 00:00:01.740\nAlright, pizza review time.\n\n00:00:01.741 --> 00:00:03.701\nSal's Pizza Factory. Oh,\n\n00:00:03.702 --> 00:00:05.701\nit's fucking pouring. We're in Charlotte.\n\n00:00:05.702 --> 00:00:07.781\nAlright man, any chance I get a real quick picture?\n\n00:00:07.782 --> 00:00:09.901\nJack or Dwight Howard? I gotta pick one.\n\n00:00:09.902 --> 00:00:10.861\nYeah, Jack.\n\n00:00:10.862 --> 00:00:12.301\nYeah, easy, right?\n\n00:00:12.302 --> 00:00:13.981\nWe're still Jason Williams still with us?\n\n00:00:13.982 --> 00:00:16.381\nYeah, he on the plane right over,\n\n00:00:16.382 --> 00:00:18.261\nout of the blue. Said the following.\n\n00:00:18.262 --> 00:00:21.141\nHe would take Dwight Howard over Shaq at center.\n\n00:00:21.142 --> 00:00:23.461\nAnd says he lie about it for the rest of his life\n\n00:00:23.462 --> 00:00:25.341\nand would never admit to saying that.\n\n00:00:25.342 --> 00 …"},"credits_used":10,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/rumble/video/comments":{"get":{"summary":"List top-level comments on a Rumble video","description":"Returns all top-level comments for a Rumble video — comment text, author, `createdAt`, `createdAtText`, `likeCount`, `dislikeCount`, and `replyCount` when comment bodies are public.","tags":["rumble"],"operationId":"get_rumble_video_comments","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Rumble video URL.","schema":{"type":"string"},"example":"https://rumble.com/v792vns-example.html"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical comment wrappers ({ comment })","items":{"type":"object","description":"Canonical comment wrapper","properties":{"comment":{"type":"object","description":"Canonical Comment object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific comment ID (always a string)"},"url":{"type":["string","null"],"description":"Direct URL to the comment on the source platform"},"parent_id":{"type":["string","null"],"description":"Parent comment ID for nested replies, or null for top-level comments"},"post_id":{"type":["string","null"],"description":"ID of the post this comment belongs to"},"text":{"type":["string","null"],"description":"Comment body. Tombstone sentinels ([deleted] / [removed]) are collapsed to null upstream — customers never see them."},"author":{"type":"object","description":"Subset of Author fields for the comment author","properties":{"username":{"type":["string","null"],"description":"Comment author username (null when tombstoned)"},"display_name":{"type":["string","null"],"description":"Comment author display name"},"avatar_url":{"type":["string","null"],"description":"URL to comment author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the comment author is verified"}}},"engagement":{"type":"object","description":"Engagement counts on the comment","properties":{"likes":{"type":["integer","null"],"description":"Like / upvote count"},"replies":{"type":["integer","null"],"description":"Reply / child-comment count. `0` when the upstream structurally reports the count and the comment has no replies; `null` only when the upstream does not surface a reply count at all."}}},"flags":{"type":"object","description":"Boolean flags on the comment","properties":{"pinned":{"type":["boolean","null"],"description":"Pinned flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the comment is tombstoned (always present, even when false)"}}},"published_at":{"type":["string","integer","null"],"description":"Comment creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `comment.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough tokens for reply expansion (present only on platforms that surface them)","properties":{"replies_token":{"type":["string","null"],"description":"YouTube reply continuation token — pass to `/v1/youtube/video/comment/replies?continuationToken=`"},"replies_cursor":{"type":["string","null"],"description":"Reddit reply-branch continuation cursor. Present when this comment's reply tree is truncated upstream — pass it back as `?cursor=` on `/v1/reddit/post/comments` to load the rest of the branch."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 string)."},"feedback_id":{"type":["string","null"],"description":"Facebook comment feedback id — feeds `/v1/facebook/post/comment/replies`"},"expansion_token":{"type":["string","null"],"description":"Facebook comment expansion/paginator token — feeds `/v1/facebook/post/comment/replies`"},"author_id":{"type":["string","null"],"description":"String at comment.ext.author_id"},"urn":{"type":["string","null"],"description":"String at comment.ext.urn"},"reaction_counts":{"type":["array","null"],"description":"Array at comment.ext.reaction_counts","items":{"type":"string","description":"Leaf at comment.ext.reaction_counts"}},"is_edited":{"type":["boolean","null"],"description":"Boolean at comment.ext.is_edited"},"previous_replies_token":{"type":["string","null"],"description":"String at comment.ext.previous_replies_token"},"updated_at":{"type":["string","null"],"description":"String at comment.ext.updated_at"},"author_channel_id":{"type":["string","null"],"description":"String at comment.ext.author_channel_id"},"author_url":{"type":["string","null"],"description":"String at comment.ext.author_url"},"viewer_rating":{"type":["string","null"],"description":"String at comment.ext.viewer_rating"},"text_original":{"type":["string","null"],"description":"String at comment.ext.text_original"},"preview_replies":{"type":["array","null"],"description":"Array at comment.ext.preview_replies","items":{"type":"string","description":"Leaf at comment.ext.preview_replies"}},"lookup":{"type":["string","null"],"description":"Leaf at comment.ext.lookup"}}},"replies":{"type":["array","null"],"description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`.","items":{"type":"object","description":"Nested reply tree — array of child comments, each itself a full Comment object with its own `replies`. Populated on threaded platforms (Reddit); absent on flat-comment platforms, which thread only via `parent_id`."}}}}}}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video/comments","data":{"items":[{"comment":{"id":"Ugzge340dBgB75hWBm54AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"can confirm: he never gave us up","author":{"username":"@YouTube","display_name":"@YouTube","avatar_url":"https://yt3.ggpht.com/3s6evpqAiDU9tQR4sC2siJippbH2RWVPnwHgyl4V0th2iuQz0VDQZbUhQBGmsxLYo-mjG6TqZQ=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":263767,"replies":1000},"flags":{"pinned":null,"deleted":false},"published_at":"2025-04-22T19:05:08Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZyJ9","updated_at":"2025-04-22T19:05:08Z","author_channel_id":"UCBR8-60-B28hp2BmDPdntcQ","author_url":"http://www.youtube.com/@YouTube","viewer_rating":"none","text_original":"can confirm: he never gave us up","preview_replies":[{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"YOUTUBE AND ONE LIKE WOOHAAAAH","textOriginal":"YOUTUBE AND ONE LIKE WOOHAAAAH","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@linganguliguliwatcha","authorProfileImageUrl":"https://yt3.ggpht.com/AbGqKNjK9k5tyOqdV7cdXx-GgnGuuGQ5wj8RN42U5YCDvYHT0vaOKXGFahR36iaDPseGN08DjQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@linganguliguliwatcha","authorChannelId":{"value":"UCjFRISlX-LPxiqViJAE3h6Q"},"canRate":true,"viewerRating":"none","likeCount":7051,"publishedAt":"2025-04-22T19:14:32Z","updatedAt":"2025-04-22T19:14:32Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAB_-JmDA","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"HEY YOUTUBE","textOriginal":"HEY YOUTUBE","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@_bugrabilgin","authorProfileImageUrl":"https://yt3.ggpht.com/LvMpN24GYYr8w43sGoMeYZYejDPJz_skehI6jm_XGGhfM5YeRa9OOsaplj60LnFNehE79ZxImg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@_bugrabilgin","authorChannelId":{"value":"UCg9tPtxMOieUEyhSv63uJ4g"},"canRate":true,"viewerRating":"none","likeCount":2969,"publishedAt":"2025-04-22T19:19:13Z","updatedAt":"2025-04-22T19:19:13Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAOCSlaNN","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"new comment alert","textOriginal":"new comment alert","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@NashiraArif","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_n1guDiz8iQIUgFGnmh5VA5PJlNSiWQwX3Ik0ywlPv8JUDRXZiF6wxDvbC7F3YSi1BdlA=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@NashiraArif","authorChannelId":{"value":"UCWrbmlBO2iW7jwhSuvLsgXQ"},"canRate":true,"viewerRating":"none","likeCount":2058,"publishedAt":"2025-04-22T19:20:56Z","updatedAt":"2025-04-22T19:20:56Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEAQwtwdoZ","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"oop 3rd didnt realise youtube was here😄","textOriginal":"oop 3rd didnt realise youtube was here😄","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@jennaortega-m4m","authorProfileImageUrl":"https://yt3.ggpht.com/ytc/AIdro_lVdgv6VK0IOScTdHt1R4NdIFdRkvG2Y1jsrCR_otHBLogTg1YjnUt3k9YQBrmAT3VFLg=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@jennaortega-m4m","authorChannelId":{"value":"UCbHhpa0tTOY_LO-uMH5ZKig"},"canRate":true,"viewerRating":"none","likeCount":908,"publishedAt":"2025-04-22T19:21:18Z","updatedAt":"2025-04-22T19:21:18Z"},{"id":"Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHEB5iPJLDp","channelId":"UCuAXFkgsw1L7xaCfnd5JJOw","videoId":"dQw4w9WgXcQ","textDisplay":"He's ingrained in our brains at this point. Such a devoted man.","textOriginal":"He's ingrained in our brains at this point. Such a devoted man.","parentId":"Ugzge340dBgB75hWBm54AaABAg","authorDisplayName":"@TheAngelofBattle99","authorProfileImageUrl":"https://yt3.ggpht.com/92UP2htp8mRB1oRt7tZ1bmid5hSmtrt-fNUlOH0sgx0zBFEwLSQ7OT0Vo8nuyWC3XSyUxNl3oMQ=s48-c-k-c0x00ffffff-no-rj","authorChannelUrl":"http://www.youtube.com/@TheAngelofBattle99","authorChannelId":{"value":"UCCejpvuOWrro8w-YM4SecQQ"},"canRate":true,"viewerRating":"none","likeCount":687,"publishedAt":"2025-04-22T19:27:09Z","updatedAt":"2025-04-22T19:27:09Z"}]}}},{"comment":{"id":"Ugzt9xJbQe-4VyOGK8x4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"I meeted the guy","author":{"username":"@jennifermcelroy2085","display_name":"@jennifermcelroy2085","avatar_url":"https://yt3.ggpht.com/ytc/AIdro_nTy0DrRqUrNPiKReDSnjaSqUcEJeTv0EqUZ-6VHjQEOs4=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:32:22Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3p0OXhKYlFlLTRWeU9HSzh4NEFhQUJBZyJ9","updated_at":"2026-07-03T22:32:22Z","author_channel_id":"UCHRSltH__Nk9yXm-aww6tgA","author_url":"http://www.youtube.com/@jennifermcelroy2085","viewer_rating":"none","text_original":"I meeted the guy"}}},{"comment":{"id":"Ugx8NOxt469g3lmMl2Z4AaABAg","url":null,"parent_id":null,"post_id":"dQw4w9WgXcQ","text":"An add saved me😀✌️","author":{"username":"@luishenriquez5032","display_name":"@luishenriquez5032","avatar_url":"https://yt3.ggpht.com/s-zg7lsesYjtXe8hvMNlFFDdWnSEQ-zQsceXM_A3sOLzCbknV09lsl6SEoy0gRrKZi2aIZx7=s48-c-k-c0x00ffffff-no-rj","verified":null},"engagement":{"likes":0,"replies":0},"flags":{"pinned":null,"deleted":false},"published_at":"2026-07-03T22:24:30Z","ext":{"replies_token":"sc2.eyJzIjoiYSIsImMiOiJVZ3g4Tk94dDQ2OWczbG1NbDJaNEFhQUJBZyJ9","updated_at":"2026-07-03T22:24:30Z","author_channel_id":"UCLn4sTEZM5X0rVl288NCvVw","author_url":"http://www.youtube.com/@luishenriquez5032","viewer_rating":"none","text_original":"An add saved me😀✌️"}}}],"next_cursor":"sc2.eyJzIjoiYSIsImMiOiJzYzEuZXlKaklqb2lXakpXTUZneU5XeGtNbFo2WkVZNWJXRllTbnBrUXpCMFVUSmtibE5YWkVKVlZscEhUakphVTFRd1NrcFNhMDVNV2pKa1NGRlZSbFJSYkVad1UwVnNRMW93UmtaYU1WWktZbXhPUWxkVlJsTlRWVnBFVTFka2JsSXdSa0pWTUVwU1lWVndTbEZ0WkVKVFYyTXdVekJTUW1GWGF6TlRhazVVVVcxb1JWZFViSHBNVjJoQ1ZWRTlQU0lzSW5NaU9sc2lWV2Q1WTNoMlQyMTRiRGRWZDBVMlRqYzBkRFJCWVVGQ1FXY2lMQ0pWWjNnMlNtaHJOemxCT0V0aE0zZEZhMDlXTkVGaFFVSkJaeUlzSWxWbmVEQk1jRmhWUjBFd05tUnplRmhpZURVMFFXRkJRa0ZuSWl3aVZXZDVjWFpVVmtFNU0wUlVUbU5FZEU5UFZqUkJZVUZDUVdjaUxDSlZaM2RNV21GT1NsOWFTREZYVlhORWNGWk9ORUZoUVVKQlp5SXNJbFZuZVZWNGFVbDJhbXRwTFhGNlZWTjBaMDQwUVdGQlFrRm5JaXdpVldkNVdVSnhlRkV3YjBod1ZpMUlPSGsxZERSQllVRkNRV2NpTENKVlozbHlOVzlCV2t4MlduSkNTbUpmU1VKc05FRmhRVUpCWnlJc0lsVm5lazlyVUdOUVMyZERaa1pEWWtSeGIzUTBRV0ZCUWtGbklpd2lWV2Q2WHpBMFZWSnVZbXBHY0c1b1NXcFFiRFJCWVVGQ1FXY2lMQ0pWWjNobWRVSnBkVXBhWTNkeE5uVllkbEJ3TkVGaFFVSkJaeUlzSWxWbmR5MUlhRmhYZVdSalpreG1lbmxtY1U0MFFXRkJRa0ZuSWl3aVZXZDZNeTFVYVVwRk9FaEtUa2hXUm5kSk5UUkJZVUZDUVdjaUxDSlZaM3BMYm14SmVURmZZMnhHUVd4VWEwNVNORUZoUVVKQlp5SXNJbFZuZUdWUlJ6QlVkRVoxVFVWb1l6QkthWEEwUVdGQlFrRm5JaXdpVldkNmRXRnlaamxRUkhsa2JYZFNjV2xUZURSQllVRkNRV2NpTENKVlozaGZhemxpTWpNdGJtRmhNR3B0YUY5c05FRmhRVUpCWnlJc0lsVm5lbEl3TUU1R00xRktNM2c0Ykdoa1dYZzBRV0ZCUWtGbklpd2lWV2Q1UzBSbGNXSkNjMFJCU2pSU2RGcFFTalJCWVVGQ1FXY2lMQ0pWWjNoaFQyRm1VRkZ1ZWxOS1Z6RkdSekJDTkVGaFFVSkJaeUlzSWxWbmVEUmtaemxwUW1neFZtNTRUbWRqZFRFMFFXRkJRa0ZuSWl3aVZXZDNUR1kxVmpWWmQyWnhWRk54UzNoRGNEUkJZVUZDUVdjaUxDSlZaM2RmU25GbVluRm5OSGhSUVdveGNEVTFORUZoUVVKQlp5SXNJbFZuZHpFMldFWTJkM2QzZHpoNU1GOXplazQwUVdGQlFrRm5JaXdpVldkM2NISktjMkZsVGtWNUxXRnBVV0ZQTlRSQllVRkNRV2NpTENKVlozazBXbUZQV25JNFVWb3lWMngwZW1wS05FRmhRVUpCWnlJc0lsVm5lbWQ0TWxCTlpuQkRlWE10VUhrNFJsSTBRV0ZCUWtGbklpd2lWV2Q0WDFKc1JDMDNUbkIxUTFseFV6bE9NVFJCWVVGQ1FXY2lMQ0pWWjNwQ09VVXlia05LT0ZWcWVVbFRkMmw0TkVGaFFVSkJaeUlzSWxWbmVWSnpUMmxJZDBSR1gyTmtTV2s1VVZJMFFXRkJRa0ZuSWl3aVZXZDRZamx2U25CNU9FeFFSbkZQYUVkZlpEUkJZVUZDUVdjaUxDSlZaM2xEVUc1VFIwODRXbkpWZFU1MVVsUTFORUZoUVVKQlp5SXNJbFZuZUZOMGNtdFplR3RNTFhWVFkyaEJNRVkwUVdGQlFrRm5JaXdpVldkNmNWTmZZV3d4ZDBWU1dqUmxZWGsxZERSQllVRkNRV2NpTENKVlozcHJObTVpYjBwaVRsZDJja2xDV1Vaa05FRmhRVUpCWnlJc0lsVm5lVVJ5Tm5CTE5HcFVheTEyY1c5bE9VSTBRV0ZCUWtGbklpd2lWV2Q1WWxwYVNWOWhkbFZ1ZVhCU01sOHhRalJCWVVGQ1FXY2lMQ0pWWjNwUk0yVkZOVmRWT1U1UU5XVTJPR1Z3TkVGaFFVSkJaeUlzSWxWbmVIb3lZbmhEVFV0MGRFOXFlRzFJYnpVMFFXRkJRa0ZuSWl3aVZXZDROV0YwY201U01WQnZNVWRYVnpkeVJqUkJZVUZDUVdjaVhYMCJ9","total":100},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoic2MyLmV5SnpJam9pWVNJc0ltTWlPaUp6WXpFdVpYbEtha2xxYjJsWGFrcFhUVVpuZVU1WGVHdE5iRm8yV2tWWk5XSlhSbGxUYm5CclVYcENNRlZVU210aWJFNVlXa1ZLVmxac2NFaFVha3BoVlRGUmQxTnJjRk5oTURWTlYycEthMU5HUmxaU2JGSlNZa1ZhZDFVd1ZuTlJNVzkzVW10YVlVMVdXa3RaYlhoUFVXeGtWbEpzVGxSV1ZuQkZWVEZrYTJKc1NYZFNhMHBXVFVWd1UxbFdWbmRUYkVaMFdrVktWRll5VFhkVmVrSlRVVzFHV0dGNlRsUmhhelZWVlZjeGIxSldaRlZpU0hCTlZqSm9RMVpXUlRsUVUwbHpTVzVOYVU5c2MybFdWMlExV1ROb01sUXlNVFJpUkdSV1pEQlZNbFJxWXpCa1JGSkNXVlZHUTFGWFkybE1RMHBXV2pObk1sTnRhSEpPZW14Q1QwVjBhRTB6WkVaaE1EbFhUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVkVRazFqUm1oV1VqQkZkMDV0VW5wbFJtaHBaVVJWTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFZqV0ZwVlZtdEZOVTB3VWxWVWJVNUZaRVU1VUZacVVrSlpWVVpEVVZkamFVeERTbFphTTJSTlYyMUdUMU5zT1dGVFJFWllWbGhPUldOR1drOU9SVVpvVVZWS1FscDVTWE5KYkZadVpWWldOR0ZWYkRKaGJYUndURmhHTmxaV1RqQmFNRFF3VVZkR1FsRnJSbTVKYVhkcFZsZGtOVmRWU25obFJrVjNZakJvZDFacE1VbFBTR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96YkhsT1Z6bENWMnQ0TWxkdVNrTlRiVXBtVTFWS2MwNUZSbWhSVlVwQ1dubEpjMGxzVm01bGF6bHlWVWRPVVZNeVpFUmFhMXBFV1d0U2VHSXpVVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTJXSHBCTUZaV1NuVlpiWEJIWTBjMWIxTlhjRkZpUkZKQ1dWVkdRMUZYWTJsTVEwcFdXak5vYldSVlNuQmtWWEJoV1ROa2VFNXVWbGxrYkVKM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1SNU1VbGhSbWhZWlZkU2FscHJlRzFsYm14dFkxVTBNRkZYUmtKUmEwWnVTV2wzYVZaWFpEWk5lVEZWWVZWd1JrOUZhRXRVYTJoWFVtNWtTazVVVWtKWlZVWkRVVmRqYVV4RFNsWmFNM0JNWW0xNFNtVlVSbVpaTW5oSFVWZDRWV0V3TlZOT1JVWm9VVlZLUWxwNVNYTkpiRlp1WlVkV1VsSjZRbFZrUlZveFZGVldiMWw2UWt0aFdFRXdVVmRHUWxGclJtNUphWGRwVmxka05tUlhSbmxhYW14UlVraHNhMkpZWkZOalYyeFVaVVJTUWxsVlJrTlJWMk5wVEVOS1Zsb3phR1poZW14cFRXcE5kR0p0Um1oTlIzQjBZVVk1YzA1RlJtaFJWVXBDV25sSmMwbHNWbTVsYkVsM1RVVTFSMDB4Umt0Tk0yYzBZa2RvYTFkWVp6QlJWMFpDVVd0R2JrbHBkMmxXVjJRMVV6QlNiR05YU2tOak1GSkNVMnBTVTJSR2NGRlRhbEpDV1ZWR1ExRlhZMmxNUTBwV1dqTm9hRlF5Um0xVlJrWjFaV3hPUzFaNlJrZFNla0pEVGtWR2FGRlZTa0phZVVselNXeFdibVZFVW10YWVteHdVVzFuZUZadE5UUlViV1JxWkZSRk1GRlhSa0pSYTBadVNXbDNhVlpYWkROVVIxa3hWbXBXV21ReVduaFdSazU0VXpOb1JHTkVVa0paVlVaRFVWZGphVXhEU2xaYU0yUm1VMjVHYlZsdVJtNU9TR2hTVVZkdmVHTkVWVEZPUlVab1VWVktRbHA1U1hOSmJGWnVaSHBGTWxkRldUSmtNMlF6Wkhwb05VMUdPWHBsYXpRd1VWZEdRbEZyUm01SmFYZHBWbGRrTTJOSVNrdGpNa1pzVkd0V05VeFhSbkJWVjBaUVRsUlNRbGxWUmtOUlYyTnBURU5LVmxvemF6QlhiVVpRVjI1Sk5GVldiM2xXTW5nd1pXMXdTMDVGUm1oUlZVcENXbmxKYzBsc1ZtNWxiV1EwVFd4Q1RscHVRa1JsV0UxMFZVaHJORkpzU1RCUlYwWkNVV3RHYmtscGQybFdWMlEwV0RGS2MxSkRNRE5VYmtJeFVURnNlRlY2YkU5TlZGSkNXVlZHUTFGWFkybE1RMHBXV2pOd1EwOVZWWGxpYTA1TFQwWldjV1ZWYkZSa01tdzBUa1ZHYUZGVlNrSmFlVWx6U1d4V2JtVldTbnBVTW14SlpEQlNSMWd5VG10VFYyczFWVlpKTUZGWFJrSlJhMFp1U1dsM2FWWlhaRFJaYW14MlUyNUNOVTlGZUZGU2JrWlFZVVZrWmxwRVVrSlpWVVpEVVZkamFVeERTbFphTTJ4RVZVYzFWRkl3T0RSWGJrcFdaRlUxTVZWc1VURk9SVVpvVVZWS1FscDVTWE5KYkZadVpVWk9NR050ZEZwbFIzUk5URmhXVkZreWFFSk5SVmt3VVZkR1FsRnJSbTVKYVhkcFZsZGtObU5XVG1aWlYzZDRaREJXVTFkcVVteFpXR3N4WkVSU1FsbFZSa05SVjJOcFRFTktWbG96Y0hKT2JUVnBZakJ3YVZSc1pESmphMnhEVjFWYWEwNUZSbWhSVlVwQ1dubEpjMGxzVm01bFZWSjVUbTVDVEU1SGNGVmhlVEV5WTFjNWJFOVZTVEJSVjBaQ1VXdEdia2xwZDJsV1YyUTFXV3h3WVZOV09XaGtiRloxWlZoQ1UwMXNPSGhSYWxKQ1dWVkdRMUZYWTJsTVEwcFdXak53VWsweVZrWk9WbVJXVDFVMVVVNVhWVEpQUjFaM1RrVkdhRkZWU2tKYWVVbHpTV3hXYm1WSWIzbFpibWhFVkZWME1HUkZPWEZsUnpGSllucFZNRkZYUmtKUmEwWnVTV2wzYVZaWFpEUk9WMFl3WTIwMVUwMVdRblpOVldSWVZucGtlVkpxVWtKWlZVWkRVVmRqYVZoWU1DSjkiLCJwIjoiY29udGludWF0aW9uVG9rZW4ifQ","has_more":true,"page_size":100}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/bluesky/profile":{"get":{"summary":"Get a Bluesky profile","description":"Returns a Bluesky user's public profile — handle, displayName, avatar, description, followersCount, followsCount, postsCount, createdAt, and verification status.","tags":["bluesky"],"operationId":"get_bluesky_profile","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"handle","in":"query","required":true,"description":"Bluesky handle (e.g. `espn.com`).","schema":{"type":"string"},"example":"espn.com"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/bluesky/user/posts":{"get":{"summary":"List a Bluesky user's posts","description":"Returns a feed of posts for a Bluesky user — uri, record text, author info, embeds, replyCount, repostCount, likeCount, quoteCount, and indexedAt. Pass either `handle` or `user_id` (Bluesky calls user IDs `did`).","tags":["bluesky"],"operationId":"get_bluesky_user_posts","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["handle","user_id"]],"parameters":[{"name":"handle","in":"query","required":false,"description":"Bluesky handle. (one of: handle, user_id — at least one required)","schema":{"type":"string"},"example":"espn.com"},{"name":"user_id","in":"query","required":false,"description":"Bluesky `did` (Bluesky's internal user ID format, e.g. `did:plc:x7d6j54pm22ufehkes6jo4jf`). (one of: handle, user_id — at least one required)","schema":{"type":"string"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"computed":{"type":"object","description":"Server-computed analytics fields (consistent across platforms)","properties":{"engagement_rate":{"type":["integer","null"],"description":"Computed engagement rate (0..1). Null when the upstream lacks enough signal."},"language":{"type":["string","null"],"description":"ISO 639-1 language code detected from the post text. Null when undetectable."},"content_category":{"type":["string","null"],"description":"Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable."},"estimated_reach":{"type":["integer","null"],"description":"Estimated reach based on views or follower count. Null when uncomputable."}}}}}},"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."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile/videos","data":{"items":[{"post":{"id":"7658005300657638669","url":"https://www.tiktok.com/@charlidamelio/video/7658005300657638669","content":{"text":"dc @lara.joanna ","media_urls":"https://v19.tiktokcdn-eu.com/4a08329b68e24d90b840a05c9244ba65/6a498c37/video/tos/alisg/tos-alisg-ve-37c799-sg/ocXRU4saOAVGYeJRAAygAjFIzOGsgRf4peSeXk/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=1135&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=OTg8NGkzZTQ8PDo1NmQ2O0BpanEzd205cmRlPDMzZzczNEAvNWM0NDFfNi8xMjExNF5eYSNmMGwyMmQ0LzBhLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owxEmiGPia440JkI3PgALU3bB7aBAlzdBEsKB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=bf18ce44&x-expires=1783202400&x-signature=8AANrRWOCWfS6xtQ9JJiHB77vxo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":16.903},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":3417578,"likes":501973,"comments":2618,"shares":6304,"saves":22989},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-02T18:51:58.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1783018318}},"computed":{"engagement_rate":0.14949,"language":null,"content_category":"other","estimated_reach":4101094}},{"post":{"id":"7657606229484670221","url":"https://www.tiktok.com/@charlidamelio/video/7657606229484670221","content":{"text":"@Alexa Davis ","media_urls":"https://v19.tiktokcdn-eu.com/07ada727f60ed77f8504c4c9aee6f992/6a498c31/video/tos/alisg/tos-alisg-ve-37c799-sg/oAmE41FRfIDnKlQAZjDgfcEsqFENRqYDSBGUSB/?a=1233&bti=MzU8OGYpNHYpNzo5ZjEuLjpkLTptNDQwOg%3D%3D&&bt=857&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=NWU8OTg2aTw6ODlpNDU1PEBpanlrNmw5cmxuPDMzZzczNEBfLTEtMy8tXzYxLzYvYTNfYSNlbGVvMmRrYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ooZRDflKEE2SIFSfsAqgFBcFEORUAY4jBDl2Yc~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=0ee7ce0e&x-expires=1783202400&x-signature=DiqCJ1sMgLvKp5k1aK2lKgBm7CU%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":10.123},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":7205601,"likes":739100,"comments":1943,"shares":6268,"saves":28516},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-07-01T17:03:22.000Z","ext":{"music_id":"7656080164593437471","published_at_epoch":1782925402}},"computed":{"engagement_rate":0.103713,"language":null,"content_category":"other","estimated_reach":8646721}},{"post":{"id":"7657287641641143565","url":"https://www.tiktok.com/@charlidamelio/video/7657287641641143565","content":{"text":null,"media_urls":"https://v19.tiktokcdn-eu.com/24d5a0ceaf069ce4435f27d4a1fb7fa5/6a498c2d/video/tos/alisg/tos-alisg-ve-37c799-sg/o4IuEqzEKBC3UgRghYEA5FEDZJDB2RL2JfePpS/?a=1233&bti=M0BzMzU8OGYpNzo5Zi5wIzEuLjpkNDQwOg%3D%3D&&bt=939&ft=ERfCkaZWD00Q12Nvr-HxzIxRA7lGF3_45SY&mime_type=video_mp4&rc=O2Q8M2k1Nzo7ODkzPGQ2NkBpM3VrZmo5cm01PDMzZzczNEBiYC0yLjU0XjQxNTMxX2FhYSNjZy5mMmRzYC9hLS1kMS9zcw%3D%3D&vvpl=1&l=20260703224143F66ABC3BD3A97DB0685C&btag=e000b0000","thumbnail_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oEEehFBRSDqxRYEZJgMgAQpzEf2PJiDEJNI7CB~tplv-tiktokx-cropcenter-q:300:400:q70.heic?dr=9232&refresh_token=7ef5f605&x-expires=1783202400&x-signature=10x4mFTkwGHZf2I3P%2FcRrZr6vTo%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=no1a&biz_tag=tt_video&s=PUBLISH&sc=cover","duration_seconds":6.467},"author":{"username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter-q:1080:1080:q70.heic?dr=9608&idc=no1a&ps=87d6e48a&refresh_token=e0b099bd&s=PUBLISH&sc=avatar&shcp=132edbea&shp=d05b14bd&t=223449c4&x-expires=1783202400&x-signature=9SsuimlpGdsdlerisiaqvDVLV3c%3D","verified":true},"engagement":{"views":5941789,"likes":941067,"comments":3165,"shares":17173,"saves":18760},"flags":{"nsfw":null,"spoiler":null,"pinned":false,"deleted":false},"published_at":"2026-06-30T20:27:04.000Z","ext":{"music_id":"7530783142774065975","published_at_epoch":1782851224}},"computed":{"engagement_rate":0.161804,"language":null,"content_category":null,"estimated_reach":7130147}}],"next_cursor":"1782516110000","total":10},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMTc4MjUxNjExMDAwMCIsInAiOiJtYXhfY3Vyc29yIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/bluesky/post":{"get":{"summary":"Get a Bluesky post","description":"Returns a single Bluesky post — record text, author info, embeds, replyCount, repostCount, likeCount, quoteCount, and a threaded `replies` array.","tags":["bluesky"],"operationId":"get_bluesky_post","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"url","in":"query","required":true,"description":"Bluesky post URL.","schema":{"type":"string"},"example":"https://bsky.app/profile/espn.com/post/3lqdfq7fkvm2g"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/spotify/artist":{"get":{"summary":"Get a Spotify artist","description":"Returns artist metadata — id, name, followers, genres, and related artists. Pass either `id` or `url`.","tags":["spotify"],"operationId":"get_spotify_artist","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Spotify artist ID. (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"Spotify artist URL. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://open.spotify.com/artist/0cGUm45nv7Z6M6qdXYQGTX"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/spotify/track":{"get":{"summary":"Get a Spotify track","description":"Returns track metadata — artists, album info, duration, playability, and sharing details. Pass either `id` or `url`.","tags":["spotify"],"operationId":"get_spotify_track","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Spotify track ID. (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"Spotify track URL. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://open.spotify.com/track/1ITJflybJsfarsUtiBvkfK"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/spotify/album":{"get":{"summary":"Get a Spotify album","description":"Returns album metadata — artists, release date, cover art, copyright info, tracks, and sharing details. Pass either `id` or `url`.","tags":["spotify"],"operationId":"get_spotify_album","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Spotify album ID. (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"Spotify album URL. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://open.spotify.com/album/0pgrg7phBbnwGJ2HBEl9EG"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"comments":{"type":["integer","null"],"description":"Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field."},"shares":{"type":["integer","null"],"description":"Share / repost / retweet count"},"saves":{"type":["integer","null"],"description":"Save / bookmark count. `null` on Instagram — the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)."}}},"flags":{"type":"object","description":"Boolean flags on the post","properties":{"nsfw":{"type":["boolean","null"],"description":"NSFW flag (null when platform does not surface)"},"spoiler":{"type":["boolean","null"],"description":"Spoiler flag (null when platform does not surface)"},"pinned":{"type":["boolean","null"],"description":"Pinned-to-profile flag (null when platform does not surface)"},"deleted":{"type":"boolean","description":"Whether the post is tombstoned (always present)"},"likes_hidden":{"type":["boolean","null"],"description":"Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts."},"comments_hidden":{"type":["boolean","null"],"description":"Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts."},"shares_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.shares_hidden"},"views_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.views_hidden"},"saves_hidden":{"type":["boolean","null"],"description":"Boolean at post.flags.saves_hidden"}}},"published_at":{"type":["string","integer","null"],"description":"Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle."},"ext":{"type":["object","null"],"description":"Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)","properties":{"music_id":{"type":["string","null"],"description":"TikTok music/clip id (exact string) — pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound"},"author_id":{"type":["string","null"],"description":"String at post.ext.author_id"},"subreddit":{"type":["string","null"],"description":"Reddit subreddit name (search/list items) — pass to `/v1/reddit/subreddit/details?subreddit=`"},"type":{"type":["string","null"],"description":"String at post.ext.type"},"content_type":{"type":["string","null"],"description":"Leaf at post.ext.content_type"},"ticker_symbols":{"type":["array","null"],"description":"Array at post.ext.ticker_symbols","items":{"type":"string","description":"String at post.ext.ticker_symbols"}},"video_view_count":{"type":["integer","null"],"description":"Instagram reel legacy 3-second-view count. `engagement.views` carries the play count (the headline 'Views' the IG app shows); this preserves the older view count. Present only on `/v1/instagram/post` for video posts."},"published_at_epoch":{"type":["integer","null"],"description":"Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form."},"usertags":{"type":["array","null"],"description":"Array at post.ext.usertags","items":{"type":"string","description":"Leaf at post.ext.usertags"}},"coauthors":{"type":["array","null"],"description":"Array at post.ext.coauthors","items":{"type":"string","description":"Leaf at post.ext.coauthors"}},"music":{"type":["string","null"],"description":"Leaf at post.ext.music"},"sponsor_tags":{"type":["array","null"],"description":"Array at post.ext.sponsor_tags","items":{"type":"string","description":"Leaf at post.ext.sponsor_tags"}},"location":{"type":["string","null"],"description":"Leaf at post.ext.location"},"reaction_counts":{"type":["array","null"],"description":"Array at post.ext.reaction_counts","items":{"type":"string","description":"Leaf at post.ext.reaction_counts"}},"share_urn":{"type":["string","null"],"description":"String at post.ext.share_urn"},"post_type":{"type":["string","null"],"description":"String at post.ext.post_type"},"download_media_urls":{"type":["array","null"],"description":"Array at post.ext.download_media_urls","items":{"type":"string","description":"Leaf at post.ext.download_media_urls"}},"tags":{"type":["array","null"],"description":"Array at post.ext.tags","items":{"type":"string","description":"String at post.ext.tags"}},"categoryId":{"type":["string","null"],"description":"String at post.ext.categoryId"},"categoryTitle":{"type":["string","null"],"description":"String at post.ext.categoryTitle"},"topicCategories":{"type":["array","null"],"description":"Array at post.ext.topicCategories","items":{"type":"string","description":"String at post.ext.topicCategories"}},"duration":{"type":["string","null"],"description":"String at post.ext.duration"},"license":{"type":["string","null"],"description":"String at post.ext.license"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at post.ext.madeForKids"},"defaultAudioLanguage":{"type":["string","null"],"description":"String at post.ext.defaultAudioLanguage"},"hasPaidProductPlacement":{"type":["boolean","null"],"description":"Boolean at post.ext.hasPaidProductPlacement"},"caption":{"type":["string","null"],"description":"String at post.ext.caption"},"position":{"type":["integer","null"],"description":"Numeric at post.ext.position"},"playlistId":{"type":["string","null"],"description":"String at post.ext.playlistId"},"videoOwnerChannelId":{"type":["string","null"],"description":"String at post.ext.videoOwnerChannelId"},"videoPublishedAt":{"type":["string","null"],"description":"String at post.ext.videoPublishedAt"},"description":{"type":["string","null"],"description":"String at post.ext.description"},"default_language":{"type":["string","null"],"description":"String at post.ext.default_language"},"playlist_item_id":{"type":["string","null"],"description":"String at post.ext.playlist_item_id"},"playlist_owner_channel_id":{"type":["string","null"],"description":"String at post.ext.playlist_owner_channel_id"},"playlist_owner_title":{"type":["string","null"],"description":"String at post.ext.playlist_owner_title"},"channel_id":{"type":["string","null"],"description":"String at post.ext.channel_id"},"video_count":{"type":["integer","null"],"description":"Numeric at post.ext.video_count"},"commerce":{"type":["string","null"],"description":"Leaf at post.ext.commerce"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"youtube","endpoint":"/v1/youtube/video","data":{"post":{"id":"dQw4w9WgXcQ","content":{"text":"Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg","duration_seconds":214,"media_urls":"https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"},"author":{"username":"UCuAXFkgsw1L7xaCfnd5JJOw","display_name":"Rick Astley","avatar_url":null,"verified":null},"engagement":{"views":1789065639,"likes":19216844,"comments":2443809,"shares":null,"saves":null},"published_at":"2009-10-25T06:57:33Z","url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","ext":{"content_type":"video","tags":["rick astley","Never Gonna Give You Up","nggyu","never gonna give you up lyrics","rick rolled","Rick Roll","rick astley official","rickrolled","Fortnite song","Fortnite event","Fortnite dance","fortnite never gonna give you up","rick roll","rickrolling","rick rolling","never gonna give you up","80s music","rick astley new","animated video","rickroll","meme songs","never gonna give u up lyrics","Rick Astley 2022","never gonna let you down","animated","rick rolls 2022","never gonna give you up karaoke"],"categoryId":"10","categoryTitle":"Music","topicCategories":["https://en.wikipedia.org/wiki/Electronic_music","https://en.wikipedia.org/wiki/Music","https://en.wikipedia.org/wiki/Pop_music","https://en.wikipedia.org/wiki/Rhythm_and_blues","https://en.wikipedia.org/wiki/Soul_music"],"duration":"PT3M34S","license":"youtube","madeForKids":false,"defaultAudioLanguage":"en","hasPaidProductPlacement":false,"caption":"true","description":"The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100.  It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”.  The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2.  The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo","default_language":"en"},"flags":{"deleted":false,"nsfw":null,"spoiler":null,"pinned":null}},"computed":{"engagement_rate":0.012107,"language":"en","content_category":"entertainment","estimated_reach":2146878767}},"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/spotify/search":{"get":{"summary":"Search Spotify","description":"Searches Spotify playlists matching a query. Note (DR-MS-09): the upstream currently returns Playlist results only, not the full track/artist/album/episode/podcast/audiobook mix — treat non-playlist result types as unavailable until this is expanded.","tags":["spotify"],"operationId":"get_spotify_search","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search query.","schema":{"type":"string"},"example":"my first million"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of search result objects","items":{"type":"object","description":"Search result item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results."},"total":{"type":["integer","null"],"description":"Total number of matching results, when the upstream provides a count. Omitted otherwise."}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false},"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}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached","dropped"]},"example":{"success":true,"platform":"google","endpoint":"/v1/google/search","data":{"items":[{"title":"My Top 50 London Restaurants (26 Jan-9 Feb 2025)","url":"https://anguscolwell.substack.com/p/my-top-50-london-restaurants-26-jan","description":"Feb 9, 2025 · 1) Bouchon Racine, Farringdon. I'm completely obsessed with it, I love it more than anywhere else, it's operating on a level above any other ..."},{"title":"The 38 Best London Restaurants According to Eater's Local Dining ...","url":"https://www.eater.com/maps/best-london-restaurants-eater-38","description":"The best meals in London, from Michelin fine dining to beloved street food, according to a longtime restaurant editor."},{"title":"LONDON by The MICHELIN Guide","url":"https://guide.michelin.com/us/en/travel-guide/london","description":"Discover the beloved restaurants and exciting new openings that everyone is talking about: London's bustling pubs, MICHELIN-Starred restaurants that are among ..."}]},"dropped":0,"credits_used":1,"credits_remaining":9999,"request_id":"req_example000000","cached":false,"pagination":{"next_cursor":"sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0","has_more":true,"page_size":10}}}}},"400":{"description":"Invalid request — missing or malformed parameters","x-error-codes":["INVALID_REQUEST"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/spotify/podcast":{"get":{"summary":"Get a Spotify podcast","description":"Returns podcast metadata. Spotify calls podcasts `shows` internally, so Spotify podcast URLs use `/show/`. Pass either `id` or `url`.","tags":["spotify"],"operationId":"get_spotify_podcast","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Spotify podcast (show) ID. (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"Spotify podcast (show) URL. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://open.spotify.com/show/3mliji9352UAk3XnWElnDV"},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"id":{"type":"string","description":"Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)"},"username":{"type":["string","null"],"description":"User handle or username"},"display_name":{"type":["string","null"],"description":"Display name or full name"},"avatar_url":{"type":["string","null"],"description":"URL to profile picture"},"bio":{"type":["string","null"],"description":"Profile biography or description"},"verified":{"type":["boolean","null"],"description":"Whether the account is verified"},"followers":{"type":["integer","null"],"description":"Number of followers"},"following":{"type":["integer","null"],"description":"Number of accounts followed"},"posts_count":{"type":["integer","null"],"description":"Total number of posts / videos / tracks / episodes"},"likes_count":{"type":["integer","null"],"description":"Total likes received across the author's content (when surfaced)"},"url":{"type":["string","null"],"description":"Direct URL to the profile page"},"location":{"type":["string","null"],"description":"ISO region code (e.g. `US`) or freeform location string when surfaced"},"external_url":{"type":["string","null"],"description":"Bio link / external website URL when surfaced by the platform"},"private":{"type":["boolean","null"],"description":"Boolean at author.private"},"joined_at":{"type":["string","null"],"description":"String at author.joined_at"},"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"},"former_usernames":{"type":["array","null"],"description":"Array at author.ext.former_usernames","items":{"type":"string","description":"String at author.ext.former_usernames"}},"public_email":{"type":["string","null"],"description":"String at author.ext.public_email"},"public_phone":{"type":["string","null"],"description":"String at author.ext.public_phone"},"business_category":{"type":["string","null"],"description":"String at author.ext.business_category"},"hd_avatar_url":{"type":["string","null"],"description":"String at author.ext.hd_avatar_url"},"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"},"followers_approximate":{"type":["boolean","null"],"description":"Boolean at author.ext.followers_approximate"},"keywords":{"type":["string","null"],"description":"String at author.ext.keywords"},"topicCategories":{"type":["array","null"],"description":"Array at author.ext.topicCategories","items":{"type":"string","description":"String at author.ext.topicCategories"}},"bannerExternalUrl":{"type":["string","null"],"description":"String at author.ext.bannerExternalUrl"},"madeForKids":{"type":["boolean","null"],"description":"Boolean at author.ext.madeForKids"},"hiddenSubscriberCount":{"type":["boolean","null"],"description":"Boolean at author.ext.hiddenSubscriberCount"},"related_playlists":{"type":["string","null"],"description":"Leaf at author.ext.related_playlists"},"topic_ids":{"type":["array","null"],"description":"Array at author.ext.topic_ids","items":{"type":"string","description":"String at author.ext.topic_ids"}},"unsubscribed_trailer":{"type":["string","null"],"description":"String at author.ext.unsubscribed_trailer"},"monthly_listeners":{"type":["integer","null"],"description":"Numeric at author.ext.monthly_listeners"},"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"},"weekly_active_users":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_active_users"},"weekly_contributions":{"type":["integer","null"],"description":"Numeric at author.ext.weekly_contributions"}}}}},"credits_used":{"type":"integer","description":"Number of credits consumed","example":1},"credits_remaining":{"type":"integer","description":"Credits remaining on your account","example":4999},"request_id":{"type":"string","description":"Unique request identifier for support","example":"req-abc123"},"cached":{"type":"boolean","description":"Whether the response was served from cache","example":false}},"required":["success","platform","endpoint","data","credits_used","credits_remaining","request_id","cached"]},"example":{"success":true,"platform":"tiktok","endpoint":"/v1/tiktok/profile","data":{"author":{"id":"5831967","username":"charlidamelio","display_name":"charli d’amelio","avatar_url":"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ee31de49ddf64b45c5b2e3c55fbd0ea4~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=bacf7094&x-expires=1783288800&x-signature=DqbVyoxw%2FdOUTBfg8T57ssAcLbQ%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8","bio":null,"url":null,"verified":true,"private":false,"followers":159000000,"following":1397,"posts_count":3174,"likes_count":-640308194,"joined_at":null},"computed":{"engagement_rate":0,"language":null,"content_category":null,"estimated_reach":0},"_warnings":["computed.engagement_rate: value fell below 0 (raw: -4.027096); clamped"]},"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"],"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":"Insufficient credits — purchase more to continue","x-error-codes":["INSUFFICIENT_CREDITS"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INSUFFICIENT_CREDITS","message":"Insufficient credits — purchase more to continue","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"],"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":"Idempotency conflict — a request with this Idempotency-Key is still in flight","x-error-codes":["IDEMPOTENCY_KEY_CONFLICT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"IDEMPOTENCY_KEY_CONFLICT","message":"Idempotency conflict — a request with this Idempotency-Key is still in flight","status":409,"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","x-error-codes":["PAYLOAD_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","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","x-error-codes":["IDEMPOTENCY_KEY_PAYLOAD_MISMATCH"],"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","status":422,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"429":{"description":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits.","x-error-codes":["CONCURRENCY_LIMIT"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"CONCURRENCY_LIMIT","message":"Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially 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 — credits automatically refunded","x-error-codes":["INTERNAL_ERROR"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"INTERNAL_ERROR","message":"Internal server error — credits automatically refunded","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, credits refunded","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, credits refunded","status":502,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}},"503":{"description":"Service unavailable — circuit breaker open for this platform, credits refunded","x-error-codes":["SERVICE_UNAVAILABLE"],"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"type":"SERVICE_UNAVAILABLE","message":"Service unavailable — circuit breaker open for this platform, credits refunded","status":503,"doc_url":"https://www.socialcrawl.dev/docs/errors"},"credits_used":0,"credits_remaining":null,"request_id":"req_abc123"}}}}}}},"/spotify/podcast/episodes":{"get":{"summary":"List a Spotify podcast's episodes","description":"Returns episodes for a Spotify podcast. Pass the `cursor` from the previous response to fetch the next page.","tags":["spotify"],"operationId":"get_spotify_podcast_episodes","security":[{"ApiKeyAuth":[]}],"x-credit-tier":"standard","x-credit-cost":1,"x-socialcrawl-oneOf":[["id","url"]],"parameters":[{"name":"id","in":"query","required":false,"description":"Spotify podcast (show) ID. (one of: id, url — at least one required)","schema":{"type":"string"}},{"name":"url","in":"query","required":false,"description":"Spotify podcast (show) URL. (one of: id, url — at least one required)","schema":{"type":"string"},"example":"https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk"},{"name":"cursor","in":"query","required":false,"description":"Cursor returned by the previous response. Omit for page 1.","schema":{"type":"integer"}},{"name":"Cache-Control","in":"header","required":false,"description":"Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.","schema":{"type":"string"},"example":"no-cache"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL.","schema":{"type":"string"},"example":"7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the request succeeded","example":true},"platform":{"type":"string","description":"Platform name","example":"tiktok"},"endpoint":{"type":"string","description":"API endpoint path","example":"/v1/tiktok/profile"},"data":{"type":"object","description":"Platform-specific response data","properties":{"items":{"type":"array","description":"Array of canonical post wrappers ({ post, computed })","items":{"type":"object","description":"Canonical post wrapper","properties":{"post":{"type":"object","description":"Canonical Post object (unified across all platforms)","properties":{"id":{"type":"string","description":"Platform-specific post ID (always a string; numeric upstream IDs are stringified)"},"url":{"type":["string","null"],"description":"Direct URL to the post on the source platform"},"content":{"type":"object","description":"Post content fields (text, media, thumbnail, duration)","properties":{"text":{"type":["string","null"],"description":"Post caption, description, or text content"},"media_urls":{"type":["string","array","null"],"description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.","items":{"type":"string","description":"URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels."}},"thumbnail_url":{"type":["string","null"],"description":"URL to thumbnail image"},"duration_seconds":{"type":["integer","null"],"description":"Video/clip duration in seconds (null for non-video posts)"}}},"author":{"type":"object","description":"Subset of Author fields for the post creator","properties":{"username":{"type":["string","null"],"description":"Author username"},"display_name":{"type":["string","null"],"description":"Author display name"},"avatar_url":{"type":["string","null"],"description":"URL to author profile picture"},"verified":{"type":["boolean","null"],"description":"Whether the author account is verified"}}},"engagement":{"type":"object","description":"Engagement counts","properties":{"views":{"type":["integer","null"],"description":"View count (if available). For Instagram video/reels this is the play count (`video_play_count`) — the headline 'Views' the IG app shows; the legacy 3-second-view count is preserved separately under `post.ext.video_view_count` on `/v1/instagram/post`."},"likes":{"type":["integer","null"],"description":"Like / reaction count"},"c