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, 358 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: &a15 page: &a1 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: &a2 - INVALID_REQUEST content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: &a3 - MISSING_API_KEY - INVALID_API_KEY content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: &a4 - INSUFFICIENT_CREDITS content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: &a5 - ENDPOINT_NOT_FOUND - RESOURCE_NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: &a6 - METHOD_NOT_ALLOWED content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: &a7 - IDEMPOTENCY_KEY_CONFLICT content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: &a8 - PAYLOAD_TOO_LARGE content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: &a9 - IDEMPOTENCY_KEY_PAYLOAD_MISMATCH content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: &a10 - CONCURRENCY_LIMIT content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: &a11 - INTERNAL_ERROR content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: &a12 - UPSTREAM_ERROR content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: &a13 - SERVICE_UNAVAILABLE content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a14 items: type: array description: Array of canonical web page wrappers ({ page }) items: type: object description: Canonical web page wrapper properties: page: *a1 next_cursor: &a17 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: &a18 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a14 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a15 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a16 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a14 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a15 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a14 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a14 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a15 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a14 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a15 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a15 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a15 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a15 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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 Revenue 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a22 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: &a23 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a20 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`. Note: since mid-July 2026 Instagram's play count is Instagram-only — it no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." likes: type: - integer - "null" description: Like / reaction count comments: type: - integer - "null" description: "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." shares: type: - integer - "null" description: Share / repost / retweet count 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. ig_play_count: type: - integer - "null" description: Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present only on `/v1/instagram/post/stats` 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: &a21 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a24 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`. Note: since mid-July 2026 Instagram's play count is Instagram-only — it no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." likes: type: - integer - "null" description: Like / reaction count comments: type: - integer - "null" description: "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." shares: type: - integer - "null" description: Share / repost / retweet count 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. ig_play_count: type: - integer - "null" description: Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present only on `/v1/instagram/post/stats` 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: &a25 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. Never: The Autobiography 📚 OUT NOW! Follow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever https://linktr.ee/rickastleynever “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. The 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. Subscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID Follow Rick Astley: Facebook: https://RickAstley.lnk.to/FBFollowID Twitter: https://RickAstley.lnk.to/TwitterID Instagram: https://RickAstley.lnk.to/InstagramID Website: https://RickAstley.lnk.to/storeID TikTok: https://RickAstley.lnk.to/TikTokID Listen to Rick Astley: Spotify: https://RickAstley.lnk.to/SpotifyID Apple Music: https://RickAstley.lnk.to/AppleMusicID Amazon Music: https://RickAstley.lnk.to/AmazonMusicID Deezer: https://RickAstley.lnk.to/DeezerID Lyrics: We’re no strangers to love You know the rules and so do I A full commitment’s what I’m thinking of You wouldn’t get this from any other guy I just wanna tell you how I’m feeling Gotta make you understand Never gonna give you up Never gonna let you down Never gonna run around and desert you Never gonna make you cry Never gonna say goodbye Never gonna tell a lie and hurt you We’ve known each other for so long Your heart’s been aching but you’re too shy to say it Inside we both know what’s been going on We know the game and we’re gonna play it And if you ask me how I’m feeling Don’t tell me you’re too blind to see Never gonna give you up Never gonna let you down Never gonna run around and desert you Never gonna make you cry Never gonna say goodbye Never gonna tell a lie and hurt you #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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/@stoolpresidente/video/7623818255903329566 - 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: &a19 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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/post/comments data: items: - comment: id: "7623869779602457374" url: null parent_id: null post_id: "7623818255903329566" text: Beach gossip in 3 months time author: username: jw22784 display_name: JW avatar_url: https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/cbec99d66023ddef2902c1111eb046c4~tplv-tiktokx-cropcenter:100:100.jpg verified: false engagement: likes: 13659 replies: 25 flags: pinned: false deleted: false published_at: 2026-04-01T19:08:53.000Z ext: published_at_epoch: 1775070533 - comment: id: "7623876579169272607" url: null parent_id: null post_id: "7623818255903329566" text: I think you and Bethany Frankel might be related…. or soulmates. one or the other author: username: cay_teague display_name: Caylah avatar_url: https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/3901b534973ea9c0501c68ecb1b88332~tplv-tiktokx-cropcenter:100:100.jpg verified: false engagement: likes: 4229 replies: 45 flags: pinned: false deleted: false published_at: 2026-04-01T19:35:29.000Z ext: published_at_epoch: 1775072129 next_cursor: "20" total: 2200 dropped: 0 credits_used: 1 credits_remaining: 9995 request_id: req-a1b2c3d4e5f6 cached: false pagination: next_cursor: sc.eyJ2IjoyLCJjIjoiMjAiLCJwIjoiY3Vyc29yIn0 has_more: true page_size: 20 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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/video/comment/replies data: items: - comment: id: "7623849601356251917" url: null parent_id: "7623828115408274207" post_id: "7623818255903329566" text: Tea by the Sea with Dave P! author: username: oakleighsinclair display_name: oakleighsinclair avatar_url: https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/879c1343fe2d07f2ed4a9de856899c16~tplv-tiktokx-cropcenter:100:100.jpg verified: false engagement: likes: 258 replies: null flags: pinned: null deleted: false published_at: 2026-04-01T17:50:55.000Z ext: published_at_epoch: 1775065855 - comment: id: "7624839492000006943" url: null parent_id: "7623828115408274207" post_id: "7623818255903329566" text: yesssss author: username: alyfromdavalley818 display_name: ᎪᏞᎽՏϴΝ ᏟϴᏞᏞᎬͲͲᎬ ՏᎻϴᎡ avatar_url: https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/50760b4566d2005dbaec8b6bc29bad6e~tplv-tiktokx-cropcenter:100:100.jpg verified: false engagement: likes: 1 replies: null flags: pinned: null deleted: false published_at: 2026-04-04T09:53:22.000Z ext: published_at_epoch: 1775296402 next_cursor: "3" total: 59 dropped: 0 credits_used: 1 credits_remaining: 9995 request_id: req-a1b2c3d4e5f6 cached: false pagination: next_cursor: sc.eyJ2IjoyLCJjIjoiMyIsInAiOiJjdXJzb3IifQ has_more: true page_size: 3 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a26 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: &a27 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: &a28 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a26 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a27 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a29 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: &a30 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a35 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: &a36 success: true platform: tiktok endpoint: /v1/tiktok/post/transcript data: id: "7499229683859426602" url: https://www.tiktok.com/@stoolpresidente/video/7499229683859426602 transcript: |- WEBVTT 00:00:00.180 --> 00:00:01.740 Alright, pizza review time. 00:00:01.741 --> 00:00:03.701 Sal's Pizza Factory. Oh, 00:00:03.702 --> 00:00:05.701 it's fucking pouring. We're in Charlotte. 00:00:05.702 --> 00:00:07.781 Alright man, any chance I get a real quick picture? 00:00:07.782 --> 00:00:09.901 Jack or Dwight Howard? I gotta pick one. 00:00:09.902 --> 00:00:10.861 Yeah, Jack. 00:00:10.862 --> 00:00:12.301 Yeah, easy, right? 00:00:12.302 --> 00:00:13.981 We're still Jason Williams still with us? 00:00:13.982 --> 00:00:16.381 Yeah, he on the plane right over, 00:00:16.382 --> 00:00:18.261 out of the blue. Said the following. 00:00:18.262 --> 00:00:21.141 He would take Dwight Howard over Shaq at center. 00:00:21.142 --> 00:00:23.461 And says he lie about it for the rest of his life 00:00:23.462 --> 00:00:25.341 and would never admit to saying that. 00: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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: &a34 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a31 items: type: array description: Array of search result objects items: type: object description: Search result item next_cursor: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: &a32 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a33 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a33 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a41 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a38 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a40 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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 sample of the accounts that liked an Instagram post. Each liker includes username, display name, avatar URL, verification status, and profile URL, alongside the post's total like count in `total`. Instagram exposes only a ranked sample of likers (roughly the first 100) — the endpoint does not paginate, and `total` reflects the full like count rather than the number of retrievable likers. 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: 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: instagram endpoint: /v1/instagram/search/music data: items: - metadata: allow_media_creation_with_music: true is_bookmarked: false is_trending_in_clips: false track: allows_saving: true audio_asset_id: "1494662545202817" audio_cluster_id: "2252835162207684" cover_artwork_thumbnail_uri: https://scontent-hel3-1.cdninstagram.com/v/t39.30808-6/737075669_71061199190385_7495716542981038660_n.jpg cover_artwork_uri: https://scontent-hel3-1.cdninstagram.com/v/t39.30808-6/737075669_71061199190385_7495716542981038660_n.jpg dark_message: null display_artist: Beyoncé duration_in_ms: 243896 fast_start_progressive_download_url: https://scontent-hel3-1.cdninstagram.com/o1/v/t2/f2/m69/AQOjRWAyAjBN8YHI-zS7HbSIDhRkA15-OJ-0kS3FseG5r2P1hlwQ6tVv4Kzgs_6ozE_-7_3xbl1pqUXoynm5nYWV.mp4 has_lyrics: false highlight_start_times_in_ms: - 10500 - 36500 - 61500 id: "1494662545202817" is_eligible_for_audio_effects: false is_eligible_for_vinyl_sticker: true is_explicit: false licensed_music_subtype: DEFAULT progressive_download_url: https://scontent-hel3-1.cdninstagram.com/o1/v/t2/f2/m69/AQOjRWAyAjBN8YHI-zS7HbSIDhRkA15-OJ-0kS3FseG5r2P1hlwQ6tVv4Kzgs_6ozE_-7_3xbl1pqUXoynm5nYWV.mp4 reactive_audio_download_url: null sanitized_title: null song_monetization_info: REVSHARE subtitle: "" title: MORNING DEW (DONK) web_30s_preview_download_url: https://scontent-hel3-1.cdninstagram.com/o1/v/t2/f2/m69/AQPlzIe8B3TBtMu3lNNeoD8Rm9WV4SncV_3zfPRBQgSfBJSlVs7YsP3X0xwwgr-ex84A5YOn6OHyXCWZByQPrx9o.mp4 duration_seconds: 243.896 - metadata: allow_media_creation_with_music: true is_bookmarked: false is_trending_in_clips: false track: allows_saving: true audio_asset_id: "203162623835617" audio_cluster_id: "178714732818051" cover_artwork_thumbnail_uri: https://scontent-hel3-1.cdninstagram.com/v/t39.30808-6/426569212_2248773155514537_1424354714209947880_n.jpg cover_artwork_uri: https://scontent-hel3-1.cdninstagram.com/v/t39.30808-6/426569212_2248773155514537_1424354714209947880_n.jpg dark_message: null display_artist: Beyoncé duration_in_ms: 200613 fast_start_progressive_download_url: https://scontent-hel3-1.cdninstagram.com/o1/v/t2/f2/m69/AQMrTpSLE7CU7Bepu9hbNRV9gxJmg-ZuV_eYmkOlzOxeOht_EEHNeN1Bs_3rEjeelhSOUsSmpocYu9UhVD7BcAE8.mp4 has_lyrics: true highlight_start_times_in_ms: - 12000 - 101000 - 39000 id: "203162623835617" is_eligible_for_audio_effects: false is_eligible_for_vinyl_sticker: true is_explicit: false licensed_music_subtype: DEFAULT progressive_download_url: https://scontent-hel3-1.cdninstagram.com/o1/v/t2/f2/m69/AQMrTpSLE7CU7Bepu9hbNRV9gxJmg-ZuV_eYmkOlzOxeOht_EEHNeN1Bs_3rEjeelhSOUsSmpocYu9UhVD7BcAE8.mp4 reactive_audio_download_url: null sanitized_title: null song_monetization_info: REVSHARE subtitle: "" title: Diva web_30s_preview_download_url: https://scontent-hel3-1.cdninstagram.com/o1/v/t2/f2/m69/AQNxpNH5SP0wRVuDr-Qwtpgt_FAycLYpxa9AKnRz-zxz-fSg-GYfYl31UxsE-WA7kYaH0kUuGGuTlTyeXdk3GMUq.mp4 duration_seconds: 200.613 next_cursor: "30" dropped: 0 credits_used: 5 credits_remaining: 9995 request_id: req-a1b2c3d4e5f6 cached: false pagination: next_cursor: sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0 has_more: true page_size: 30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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`. When no transcript exists (the owner disabled captions, the video is login-gated or gone, or no caption track matches the requested language) the endpoint returns 404 RESOURCE_NOT_FOUND with `error.details.reason` set to `captions_disabled`, `login_required`, `no_captions`, or `video_gone` — no credits are charged, and retrying returns the same result. 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 no caption track matches the language you specify, the request returns 404 RESOURCE_NOT_FOUND (reason `no_captions`) at 0 credits. schema: type: string - name: Cache-Control in: header required: false description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details. schema: type: string example: no-cache - name: Idempotency-Key in: header required: false description: Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL. schema: type: string example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the request succeeded example: true platform: type: string description: Platform name example: tiktok endpoint: type: string description: API endpoint path example: /v1/tiktok/profile data: type: object description: Platform-specific response data properties: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a37 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a37 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a37 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a37 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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. **Two caveats worth knowing before you grade on these numbers:** (1) `engagement.views` here is Facebook's ROUNDED public display value (the "12K" / "2.6M" the page shows, parsed back to a number — e.g. 12000 where the true count is 12366), not an exact count; (2) the upstream carries no per-reel engagement beyond that view count. For EXACT views plus likes, comments, and shares, the easiest path is `GET /v1/facebook/profile/reels/full`, which runs this list and the per-reel lookups server-side and merges the exact engagement in (flat 5 credits per page of 10 reels). Alternatively, take each item's `post.url` and pass it to `/v1/facebook/post` (single) or batch up to 100 of them into `POST /v1/prism/post-stats` (1 credit per successful URL, dead links refunded). tags: - facebook operationId: get_facebook_profile_reels security: - ApiKeyAuth: [] 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a39 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a38 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a46 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a39 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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 (default 20, max 700). Search is a synchronous live scrape whose latency grows with depth; the 20-row default keeps keyword→ASIN resolution fast and reliable. Higher depth returns more rows at the same flat credit cost but takes longer (a timeout is auto-refunded). 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: *a40 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a41 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a38 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a42 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a40 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a41 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a38 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a42 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a43 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a43 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a29 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a30 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a38 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a44 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: *a17 total: *a18 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: &a45 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a38 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a44 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a44 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a44 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a45 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a38 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a44 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a44 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a46 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a38 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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_". 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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 `` 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a35 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a36 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a19 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a28 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a24 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a25 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a31 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a32 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a22 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a23 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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: *a20 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a21 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /search/everywhere: get: summary: Universal social search across 12 platforms description: "Fans out a single query across Reddit, X (ai-search), YouTube, TikTok, Instagram, Hacker News, Polymarket, GitHub, Threads, Pinterest, Perplexity, and Tavily in parallel. Returns ranked + clustered results, enriched with **real-people comments** from each post — Reddit upvoted comments, HackerNews thread replies, YouTube/TikTok/Instagram top-liked comments, GitHub issue discussion. The top comment per result lives at `data.items[i].source_items[0].metadata.top_comments[]` (sorted by score descending, capped at 5, max 300-char excerpts). Supports streaming via `Accept: text/event-stream` (emits `comments_enriched` chunks per candidate as enrichment lands, before the terminal `done`) and sync via `Accept: application/json`. Flat 20 credits per call regardless of enrichment." tags: - search operationId: get_search_everywhere security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 20 parameters: - name: query in: query required: true description: Search query (1–512 chars) schema: type: string example: kanye west - name: lookback_days in: query required: false description: Days to look back (1–365+, default 30); mutually exclusive with from_date/to_date. schema: type: integer example: 30 - name: from_date in: query required: false description: ISO YYYY-MM-DD lower bound; mutually exclusive with lookback_days. schema: type: string - name: to_date in: query required: false description: ISO YYYY-MM-DD upper bound; defaults to today when from_date is set alone. schema: type: string - name: sources in: query required: false description: Optional CSV allowlist of source names (mutually exclusive with exclude). schema: type: string example: reddit,youtube,github - name: exclude in: query required: false description: Optional CSV blocklist of source names (mutually exclusive with sources). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /search/forums: get: summary: Fused forum search across Reddit, Hacker News, and Naver 지식iN/카페 — with top comments inline on hero threads by default. description: Fans your topic across Reddit, Hacker News, and Korean forums, RRF-fuses + clusters the threads, and enriches hero threads with their top comments by default (East + West). Naver threads are labeled raw (no comment endpoint). Returns a fused `items[]`, raw per-source buckets, thread clusters, and a deterministic computed block (question_share, top_communities). Flat 10cr with coverage-based partial refund. tags: - search operationId: get_search_forums security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 10 parameters: - name: query in: query required: true description: Search query (2–256 chars), forwarded to every forum search. schema: type: string example: airpods pro 3 battery - name: sources in: query required: false description: Optional CSV allowlist of forum sources (reddit, hackernews, naver_kin, naver_cafe). Mutually exclusive with exclude. schema: type: string example: reddit,hackernews,naver_kin - name: exclude in: query required: false description: Optional CSV blocklist of forum sources. Mutually exclusive with sources. schema: type: string - name: comments in: query required: false description: Comment enrichment toggle (on|off, default on). 'off' returns thread-only. schema: type: string example: on - name: timeframe in: query required: false description: Recency window passed to Reddit; HN filtered client-side (all|day|week|month|year, default all). schema: type: string - name: lookback_days in: query required: false description: Alt recency window in days (1–365); HN filtered client-side. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/lookup: get: summary: "Universal URL dispatcher: any social/commerce URL → the right detail endpoint's unified response." description: Sniffs the platform + endpoint from a URL and returns that endpoint's unified data, with no surcharge — you pay the resolved endpoint's own cost. The join key the whole API runs on is `url`. Supports TikTok, Instagram, YouTube, X/Twitter, Facebook, LinkedIn, Bluesky, Pinterest, Reddit, Threads, Rumble, Truth Social, GitHub, Amazon, and Spotify links. The `resolved` block names the platform, endpoint, and archetype of the response so agents know the shape that follows; `legs[]` reports the dispatched call's status, cost, and latency. tags: - prism operationId: get_prism_lookup security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 0 parameters: - name: url in: query required: true description: Absolute http(s) URL of the post / profile / product to resolve. schema: type: string example: https://www.youtube.com/watch?v=dQw4w9WgXcQ - name: include in: query required: false description: CSV of optional flags to forward verbatim to the resolved endpoint (e.g. `trim`). Each member must be an optional param of that endpoint. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/comments: get: summary: Every comment on a post, replies nested, server-paginated to completion. description: "Give it any TikTok, YouTube, Facebook, Reddit, Hacker News, or Instagram post URL and it harvests every top-level comment — paginated to the end — with replies nested where the platform supports it (TikTok, YouTube, Facebook). Reddit and Hacker News return their whole nested thread; Instagram is top-level only. Pass `sort=top` to get the most-liked comments first (ranked by `engagement.likes`) — ideal for pulling the top comments on a high-volume post; pair it with `limit` to cap how many you get back (e.g. `sort=top&max=500&limit=200` scans ~500 and returns the top 200). YouTube sorts upstream so its top set is exact; other platforms are sorted across the scanned set. Metered at 1 credit per internal page call (minimum 2) — `sort`/`limit` never change the price, which always follows pages scanned (`max`). Returns sync JSON, or a typed SSE stream when you send `Accept: text/event-stream` — a `page` chunk lands as each page settles. The `next_cursor` is one opaque token that resumes every leg; `legs[]` reports each page's status, cost, and latency." tags: - prism operationId: get_prism_comments security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 1 parameters: - name: url in: query required: true description: Absolute http(s) URL of the post whose comments to harvest. schema: type: string example: https://www.youtube.com/watch?v=dQw4w9WgXcQ - name: max in: query required: false description: Stop after roughly this many top-level comments (1–5000, default 1000). Whole pages are returned, so the actual count can slightly exceed this. Drives billing and, for `sort=top`, the depth of the ranking scan. schema: type: integer - name: replies in: query required: false description: Expand replies for comments that have them, where the platform supports it (default true; TikTok/YouTube/Facebook only). Pair with `replies=false` when you only want the top comments. schema: type: boolean example: true - name: cursor in: query required: false description: Opaque composite cursor from a prior response's `next_cursor` to resume harvesting. schema: type: string - name: sort in: query required: false description: "`recent` (default — natural order) or `top` (most-liked first, ranked by each comment's like count). With `top`, the response adds `sorted_by: \"likes_desc\"`." schema: type: string enum: - top - recent example: top - name: limit in: query required: false description: Cap on how many top-level comments to return after sorting/scanning (1–5000, defaults to `max`). Truncates only the returned set — never what was scanned or billed. The response reports `returned`. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: TikTok profile, recent posts, and computed analytics in one call. description: "Fans out to the TikTok profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics — average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can't be fetched the call still returns the profile with post-dependent metrics null, and every leg's status is surfaced in legs[]. Flat 5 credits." tags: - tiktok - prism operationId: get_tiktok_profile_full security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 5 parameters: - name: handle in: query required: false description: handle schema: type: string example: mrbeast - name: user_id in: query required: false description: user_id schema: type: string - name: posts in: query required: false description: How many recent posts to fetch + average the computed metrics over (1–100, default 25). schema: type: integer example: 25 - name: cursor in: query required: false description: Pass a prior response's posts_cursor to deepen the post window. schema: type: string - name: include in: query required: false description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: Instagram profile, recent posts, and computed analytics in one call. description: "Fans out to the Instagram profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics — average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can't be fetched the call still returns the profile with post-dependent metrics null, and every leg's status is surfaced in legs[]. Flat 5 credits." tags: - instagram - prism operationId: get_instagram_profile_full security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 5 parameters: - name: handle in: query required: false description: handle schema: type: string example: mrbeast - name: posts in: query required: false description: How many recent posts to fetch + average the computed metrics over (1–100, default 25). schema: type: integer example: 25 - name: cursor in: query required: false description: Pass a prior response's posts_cursor to deepen the post window. schema: type: string - name: include in: query required: false description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/profile/full: get: summary: YouTube profile, recent posts, and computed analytics in one call. description: "Fans out to the YouTube profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics — average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can't be fetched the call still returns the profile with post-dependent metrics null, and every leg's status is surfaced in legs[]. Flat 5 credits." tags: - youtube - prism operationId: get_youtube_profile_full security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 5 parameters: - name: handle in: query required: false description: handle schema: type: string example: mrbeast - name: channelId in: query required: false description: channelId schema: type: string - name: url in: query required: false description: url schema: type: string - name: posts in: query required: false description: How many recent posts to fetch + average the computed metrics over (1–100, default 25). schema: type: integer example: 25 - name: cursor in: query required: false description: Pass a prior response's posts_cursor to deepen the post window. schema: type: string - name: include in: query required: false description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: X (Twitter) profile, recent posts, and computed analytics in one call. description: "Fans out to the X (Twitter) profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics — average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can't be fetched the call still returns the profile with post-dependent metrics null, and every leg's status is surfaced in legs[]. Flat 5 credits." tags: - twitter - prism operationId: get_twitter_profile_full security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 5 parameters: - name: handle in: query required: false description: handle schema: type: string example: mrbeast - name: posts in: query required: false description: How many recent posts to fetch + average the computed metrics over (1–100, default 25). schema: type: integer example: 25 - name: cursor in: query required: false description: Pass a prior response's posts_cursor to deepen the post window. schema: type: string - name: include in: query required: false description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: Facebook profile, recent posts, and computed analytics in one call. description: "Fans out to the Facebook profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics: average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can't be fetched the call still returns the profile with post-dependent metrics null, and every leg's status is surfaced in legs[]. Flat 5 credits. For Facebook, `author.following` and `author.posts_count` remain null because the profile upstream does not provide those totals." tags: - facebook - prism operationId: get_facebook_profile_full security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 5 parameters: - name: url in: query required: false description: url schema: type: string example: https://www.facebook.com/mrbeast - name: posts in: query required: false description: How many recent posts to fetch + average the computed metrics over (1–100, default 25). schema: type: integer example: 25 - name: cursor in: query required: false description: Pass a prior response's posts_cursor to deepen the post window. schema: type: string - name: include in: query required: false description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: LinkedIn company profile, recent posts, and computed analytics in one call. description: "Fans out to the LinkedIn company profile and recent-posts endpoints in parallel and returns the unified author, the recent-post list, and computed metrics — average engagement rate, posting cadence (with the window it was measured over), the top post, and the format mix. The profile leg is the only critical leg: if posts can't be fetched the call still returns the profile with post-dependent metrics null, and every leg's status is surfaced in legs[]. Flat 5 credits." tags: - linkedin - prism operationId: get_linkedin_profile_full security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 5 parameters: - name: url in: query required: false description: url schema: type: string example: https://www.linkedin.com/company/microsoft - name: posts in: query required: false description: How many recent posts to fetch + average the computed metrics over (1–100, default 25). schema: type: integer example: 25 - name: cursor in: query required: false description: Pass a prior response's posts_cursor to deepen the post window. schema: type: string - name: include in: query required: false description: CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: Instagram reels with views, likes, comments, and per-reel share counts where available, in one call. description: "Returns a creator's recent reels with views, likes, comments, and the per-reel share count merged in wherever the upstream exposes it — in a single call. ScrapeCreators' standard /profile/reels endpoint returns views/likes/comments but leaves engagement.shares null (its upstream has no per-post reshare count); this composite fans out to a second mobile source that carries the share number and merges it back onto each item by post id. Share coverage is best-effort and varies by account: the mobile source only exposes reshare_count for the items it returns, so some (sometimes most) items keep engagement.shares null — that null means \"upstream doesn't expose it\", not \"zero\". Read shares_coverage (the fraction of returned items that got a real share number) before relying on shares; legs[] shows each leg's status. Billing: the ScrapeCreators leg is critical (its failure refunds the full call); the shares leg is best-effort — if it fails OUTRIGHT the items still return with shares null and 4 of the 5 credits are refunded (you pay the standard 1-credit list price). A successful shares leg with low coverage is still the flat 5 credits, since the second source was queried regardless of how many items it happened to cover. Paginate with next_cursor." tags: - instagram - prism operationId: get_instagram_profile_reels_full 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 (with or without a leading @). Required unless user_id is given. The share-count leg needs a handle; a user_id-only call returns views/likes/comments with shares null (partial refund). (one of: handle, user_id — at least one required)" schema: type: string example: sid.and.listen - name: user_id in: query required: false description: "Numeric Instagram user id. Alternative to handle. (one of: handle, user_id — at least one required)" schema: type: string - name: cursor in: query required: false description: Opaque cursor from a prior response's next_cursor to page deeper. schema: type: string - name: limit in: query required: false description: Return up to this many items in one call (1–50). The endpoint pages the underlying source server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page). Omit for a single page. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: Instagram posts with views, likes, comments, and per-post share counts where available, in one call. description: "Returns a creator's recent posts with views, likes, comments, and the per-post share count merged in wherever the upstream exposes it — in a single call. ScrapeCreators' standard /profile/posts endpoint returns views/likes/comments but leaves engagement.shares null (its upstream has no per-post reshare count); this composite fans out to a second mobile source that carries the share number and merges it back onto each item by post id. Share coverage is best-effort and varies by account: the mobile source only exposes reshare_count for the items it returns, so some (sometimes most) items keep engagement.shares null — that null means \"upstream doesn't expose it\", not \"zero\". Read shares_coverage (the fraction of returned items that got a real share number) before relying on shares; legs[] shows each leg's status. Billing: the ScrapeCreators leg is critical (its failure refunds the full call); the shares leg is best-effort — if it fails OUTRIGHT the items still return with shares null and 4 of the 5 credits are refunded (you pay the standard 1-credit list price). A successful shares leg with low coverage is still the flat 5 credits, since the second source was queried regardless of how many items it happened to cover. Paginate with next_cursor." tags: - instagram - prism operationId: get_instagram_profile_posts_full 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 (with or without a leading @). Required unless user_id is given. The share-count leg needs a handle; a user_id-only call returns views/likes/comments with shares null (partial refund). (one of: handle, user_id — at least one required)" schema: type: string example: sid.and.listen - name: user_id in: query required: false description: "Numeric Instagram user id. Alternative to handle. (one of: handle, user_id — at least one required)" schema: type: string - name: cursor in: query required: false description: Opaque cursor from a prior response's next_cursor to page deeper. schema: type: string - name: limit in: query required: false description: Return up to this many items in one call (1–50). The endpoint pages the underlying source server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page). Omit for a single page. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/full: get: summary: Facebook profile reels with exact views, likes, comments, and shares merged in, in one call. description: "Returns a Facebook page or profile's reels with EXACT per-reel engagement merged in — one call instead of the reels-list → post-stats chain. The plain `/v1/facebook/profile/reels` list only carries a rounded public view count (\"12K\" parsed back to 12000) and no likes, comments, or shares, because Facebook exposes those on the individual reel permalink only. This endpoint fetches the list, then queries each reel's permalink server-side and overwrites the item's `engagement` with the exact figures: `views` (the rounded list value is replaced), `likes`, `comments`, and `shares`. `saves` stays null (Facebook exposes no public save count), and `comments` can be null on a zero-comment reel (a quirk of the permalink upstream). Per-item `ext.engagement_source` is `\"post_detail\"` when the exact figures landed and null when that reel's lookup failed (the item then keeps the honest list values); read `engagement_coverage` before grading, and `_warnings: [\"engagement_partial\"]` flags a partial page. Billing: a flat 5 credits per page of 10 reels (1 credit for the list + 4 for the per-reel enrichment, roughly half the cost of running the chain yourself); if enrichment yields zero coverage the 4-credit premium is refunded automatically. Paginate with `next_cursor`, or pass `limit` (1–50) to have the endpoint walk pages server-side until it has collected that many reels, billed per page consumed." tags: - facebook - prism operationId: get_facebook_profile_reels_full security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 5 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: cursor in: query required: false description: Cursor from a prior response's next_cursor to page deeper. schema: type: string - name: limit in: query required: false description: 'Return up to this many reels in one call (1–50). The endpoint pages the underlying list server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page of 10). If the walk hits the internal time budget first, the response carries `_warnings: ["walk_deadline_reached"]`, unfetched pages are refunded, and `next_cursor` resumes where it stopped. Omit for a single page.' schema: type: integer - name: Cache-Control in: header required: false description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details. schema: type: string example: no-cache - name: Idempotency-Key in: header required: false description: Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL. schema: type: string example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the request succeeded example: true platform: type: string description: Platform name example: tiktok endpoint: type: string description: API endpoint path example: /v1/tiktok/profile data: type: object description: Platform-specific response data properties: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/omni-search: get: summary: "Reddit VoC sweep: one keyword → threads across all of Reddit with subreddit attribution and top comments inline." description: "Runs reddit/search, expands the top N threads' comments in parallel (capped 15/thread), and rolls up which subreddits are talking — volume + a per-community tone label. Returns sync JSON or a typed SSE stream that emits each thread as its comments land. Metered at 1 credit per search page + 1 credit per successfully-expanded thread (minimum 5); a failed thread isn't billed and the unused thread ceiling is refunded. `subreddit=` scopes the sweep to one community. The `next_cursor` resumes the search. Honest note: Reddit search is the slowest social search on the API (10–12s) and relevance is loose — a VoC sweep, not precision ranking." tags: - reddit - prism operationId: get_reddit_omni_search security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 1 parameters: - name: query in: query required: true description: Keyword or phrase to sweep across Reddit. schema: type: string example: best mechanical keyboard - name: threads in: query required: false description: How many top threads to expand comments for (1–8, default 8). schema: type: integer example: 5 - name: sort in: query required: false description: Search sort order (relevance | new | top | comment_count). schema: type: string enum: - relevance - new - top - comment_count - name: timeframe in: query required: false description: Time window for the search (all | day | week | month | year). schema: type: string enum: - all - day - week - month - year - name: subreddit in: query required: false description: Scope the sweep to one subreddit (bare name, no r/ prefix). schema: type: string - name: cursor in: query required: false description: Opaque cursor from a prior response's next_cursor to page deeper. schema: type: string - name: include in: query required: false description: CSV subset of subreddits,comments (default both). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/brand-mentions: get: summary: Brand mention volume time-series, sentiment split, top sources, and recent mentions for one keyword. description: Fans out to content_analysis summary, phrase-trends, and search in parallel, then folds them into one envelope with a computed volume/sentiment trajectory (OLS slope + a noise-aware direction) and an optional LLM digest (`include=digest`). Sentiment is NLP-derived (content_analysis), and mention freshness lags the live web by days. The `computed` block carries stable keys + a `methodology_version` so a monitor can diff runs. `legs[]` reports each leg's status, cost, and latency; if one of the three data legs fails the call still returns a degraded result, and a strict-majority failure refunds half. tags: - prism operationId: get_prism_brand_mentions security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 50 parameters: - name: keyword in: query required: true description: The brand or term to track. Wrap in quotes for exact-phrase semantics. schema: type: string example: socialcrawl - name: date_from in: query required: true description: Window start (YYYY-MM-DD). Required by the trend leg. schema: type: string example: 2026-06-01 - name: date_to in: query required: false description: Window end (YYYY-MM-DD). Defaults to the latest crawl. schema: type: string - name: date_group in: query required: false description: "Trend bucket size: day (default), week, or month." schema: type: string enum: - day - week - month - name: page_type in: query required: false description: "Optional surface filter: ecommerce, news, blogs, message-boards, or organization." schema: type: string enum: - ecommerce - news - blogs - message-boards - organization - name: include in: query required: false description: Set `digest` to add an LLM narrative summary leg. schema: type: string example: digest - name: Cache-Control in: header required: false description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details. schema: type: string example: no-cache - name: Idempotency-Key in: header required: false description: Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL. schema: type: string example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the request succeeded example: true platform: type: string description: Platform name example: tiktok endpoint: type: string description: API endpoint path example: /v1/tiktok/profile data: type: object description: Platform-specific response data properties: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/demand-signals: get: summary: "Consumer-demand nowcast: app-review velocity, web mention slope, Reddit velocity, and commerce review levels, fused into a published demand index." description: "Reads up to four consumer-demand axes in parallel — app-review velocity (the freshest public channel), web mention slope (content_analysis phrase-trends, a real stateless time-series), Reddit sort=new velocity, and Amazon review-count level — and fuses them into published demand-index inputs (never an opaque score; every weight, anchor, and observation window is disclosed). v1 is an honest one-shot level+slope: three of the four axes are point-in-time rates/levels whose true week-over-week deltas need a monitor (the methodology block names them). Supply google_play_id/app_store_id for the app-review axis. legs[] reports each leg status, cost, and latency; a strict-majority leg failure refunds half. Flat 30 credits." tags: - prism operationId: get_prism_demand_signals security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 30 parameters: - name: keyword in: query required: true description: The brand or product to nowcast. Drives the mention, Reddit, and Amazon legs. schema: type: string example: spotify - name: google_play_id in: query required: false description: Google Play package name (e.g. com.spotify.music) for the app-review velocity axis. schema: type: string example: com.spotify.music - name: app_store_id in: query required: false description: Apple App Store numeric id for the app-review velocity axis. schema: type: string - name: signals in: query required: false description: CSV subset of app_reviews,mentions,reddit,commerce (default all). app_reviews is dropped when no app id is supplied. schema: type: string example: app_reviews,mentions,reddit,commerce - name: amazon_query in: query required: false description: Override the Amazon product-search term if it differs from the brand. schema: type: string - name: country in: query required: false description: Location for the app-review legs (default United States); a 2-letter code is also applied to the Amazon leg. schema: type: string - name: date_from in: query required: false description: Window start (YYYY-MM-DD) for the mention-slope leg. Defaults to 30 days ago. schema: type: string - name: date_to in: query required: false description: Window end (YYYY-MM-DD). Defaults to today. schema: type: string - name: depth in: query required: false description: Reviews per store for the velocity computation (1-600, default 150). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/campaign: get: summary: "Campaign tracker: pre/during/post volume lift, cross-platform engagement, and ranked top amplifiers for a hashtag or phrase." description: Fans out to content_analysis phrase-trends (pre/during/post windows), search/everywhere (consuming items_by_source for real per-platform engagement, not the capped fused items), and tiktok/youtube search for amplifier discovery, then folds them into a lift report (volume lift %, sustained-floor check, ranked amplifiers). YouTube amplifiers are undated in fusion — pass include=amplifier_dates to date the top ones via direct youtube/video calls. Supply hashtag OR phrase plus window_start; window_end defaults to today. legs[] reports each leg; losing the CA timeline or the everywhere engagement spine refunds half. Flat 35 credits. tags: - prism operationId: get_prism_campaign security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 35 x-socialcrawl-oneOf: - - hashtag - phrase parameters: - name: hashtag in: query required: false description: "The campaign hashtag (with or without #). One of hashtag or phrase is required. (one of: hashtag, phrase — at least one required)" schema: type: string example: summergiveaway - name: phrase in: query required: false description: "A campaign slogan/phrase instead of a hashtag. One of hashtag or phrase is required. (one of: hashtag, phrase — at least one required)" schema: type: string - name: window_start in: query required: false description: Campaign launch date (YYYY-MM-DD) — the pre/during boundary. Optional; defaults to 30 days ago. schema: type: string example: 2026-06-01 - name: window_end in: query required: false description: Campaign end date (YYYY-MM-DD) — the during/post boundary. Defaults to today. schema: type: string - name: pre_days in: query required: false description: Baseline days before window_start for lift measurement (1-90, default 14). schema: type: integer - name: post_days in: query required: false description: Days after window_end for the post window (0-90, default 14; 0 = no post window). schema: type: integer - name: include in: query required: false description: Set amplifier_dates to date YouTube amplifiers via direct youtube/video calls (undated in fusion). schema: type: string example: amplifier_dates - name: Cache-Control in: header required: false description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details. schema: type: string example: no-cache - name: Idempotency-Key in: header required: false description: Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL. schema: type: string example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the request succeeded example: true platform: type: string description: Platform name example: tiktok endpoint: type: string description: API endpoint path example: /v1/tiktok/profile data: type: object description: Platform-specific response data properties: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/ai-visibility: get: summary: "AI Share-of-Voice / GEO monitoring: prompt set x reruns to per-brand appearance-% per AI engine plus a cited-domain ranking." description: Probes your brand (and competitors) across grounded-answer AI engines (Perplexity Sonar + Grok) over a prompt set with N reruns, then reports the share of runs your brand appeared in per engine (appearance-%, never volatile rank) plus a ranking of the domains those engines cite. Add include=web_baseline to see which AI-cited domains you do not yet rank on. Metered 2 credits per probe (one prompt x run x engine); use preset=quick|standard|deep for a flat budget. v1 detects mentions deterministically via recognition tokens. Supply brand plus prompts (or a topic). The self-serve entry tier of Profound/Otterly/Peec. tags: - prism - geo - ai-search operationId: get_prism_ai_visibility security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 2 parameters: - name: brand in: query required: false description: The brand whose appearance-% is measured (required). Matched against each answer plus its aliases. schema: type: string example: socialcrawl - name: prompts in: query required: false description: The category prompts to probe, as a JSON array or a pipe-delimited list (1-20). One of prompts or topic is required. schema: type: string - name: topic in: query required: false description: A topic probed as a single prompt in v1 (one of prompts or topic is required). schema: type: string example: social media data api - name: competitors in: query required: false description: CSV of up to 5 competitors also measured for appearance-% from the same answers. schema: type: string example: apify,bright data - name: engines in: query required: false description: CSV subset of perplexity,grok (default both) — the grounded-answer engines probed. schema: type: string - name: runs in: query required: false description: Reruns per (prompt, engine) to measure variance (1-20, default 8). schema: type: integer - name: preset in: query required: false description: quick|standard|deep — sets runs and caps prompts for a flat probe budget. schema: type: string enum: - quick - standard - deep example: standard - name: include in: query required: false description: Set web_baseline to cross-join AI-cited domains against your web top domains. schema: type: string - name: brand_domains in: query required: false description: CSV of your own domains so the citation ranking can flag the ones you already rank on. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/crisis-postmortem: get: summary: "Crisis post-mortem: a who-said-what-first timeline across web, Reddit, Hacker News, and social, with an origin, peak, propagation sequence, and a grounded narrative." description: "Reconstructs a crisis window: content_analysis phrase-trends (volume curve) + anger-ordered search + reddit (sort=new) + hackernews (client-side date-filtered so stale relevance-ranked posts cannot corrupt the chronology) + search/everywhere (items_by_source cross-platform spread), merged into one chronologically-sorted event timeline with the first credible origin, the peak day, and the platform-by-platform propagation order. Pass include= (empty) to drop the LLM narrative and get the raw timeline. Origin is chosen only from natively-dated events (a lagged crawl time cannot establish who-said-it-first). Supply brand plus window_start; window_end defaults to today. Flat 35 credits; losing more than half the timeline sources refunds half." tags: - prism operationId: get_prism_crisis_postmortem security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 35 parameters: - name: brand in: query required: true description: The brand or entity the crisis is about (required). schema: type: string example: acme - name: window_start in: query required: false description: Start of the crisis window (YYYY-MM-DD) — the earliest point on the timeline. Optional; defaults to 30 days ago. schema: type: string example: 2026-06-02 - name: window_end in: query required: false description: End of the crisis window (YYYY-MM-DD). Defaults to today. schema: type: string - name: crisis_terms in: query required: false description: Optional CSV of up to 5 terms (e.g. recall,defect) that scope the legs to the actual incident. schema: type: string example: breach,leak - name: include in: query required: false description: narrative (default on) adds the grounded LLM propagation narrative; pass an empty value for the raw timeline only. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/crisis-radar: get: summary: "Stateless crisis breach check: a z-score on daily mention volume and negative share, with on-breach confirmation and a severity grade." description: Stage 1 computes a 7-day-rolling z-score on content_analysis daily phrase-trends (the breach gate, always 15 credits) and returns a calm|watch|alert|crisis status. On a breach with confirm=true, Stage 2 fans out to sentiment + search/everywhere (items_by_source real counts) + reddit (sort=new) + twitter/ai-search (citations, not the chatty answer) + a triage anger-ordered search, then grades severity (+30 credits, charged only when a breach actually fires). A calm result or confirm=false costs only the 15cr baseline. The recurring alarm is delivered by wrapping this recipe in a monitor. tags: - prism operationId: get_prism_crisis_radar security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 15 parameters: - name: brand in: query required: false description: The brand to watch (required). schema: type: string example: socialcrawl - name: sensitivity in: query required: false description: Z-score breach threshold (0.5-6, default 2.0). z>=sensitivity on volume or negative-share fires a breach. schema: type: string example: "2.0" - name: confirm in: query required: false description: true -> on a breach, run the escalation legs and grade severity (+30 credits, charged only when a breach fires). schema: type: boolean example: true - name: baseline_days in: query required: false description: Rolling-mean window for the z-score (3-30, default 7). schema: type: integer - name: date_to in: query required: false description: The day being evaluated (YYYY-MM-DD). Defaults to today. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/devtool-pulse: get: summary: "Developer-brand health: a devtool's repo dossier + Hacker News reaction + Reddit chatter + dev-blog echo, in one call." description: "Fans out a GitHub repo/dossier, a Hacker News search+comment pull, a Reddit search+comment pull, and the dev-blog web echo (content_analysis), then folds them into a developer-brand health snapshot: release recency, open-issue load, the top feature request and top complaint, HN and Reddit attention, the web echo with its top domains, a deterministic pulse=strong|steady|cooling|quiet label, and a soft NLP sentiment label. No leg is individually critical — absence is signal; a strict-majority leg failure refunds half. Supply `repo=` (owner/repo or a github URL) to anchor the dossier; without it the server best-effort resolves one from the HN/web legs. `legs[]` reports each leg's status, cost, and latency." tags: - prism operationId: get_prism_devtool_pulse security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: query in: query required: true description: The devtool name to sweep across Hacker News, Reddit, and the dev-blog index (e.g. Bun, Drizzle ORM, tRPC). schema: type: string example: Bun - name: repo in: query required: false description: The repo to dossier — owner/repo or a github.com/{owner}/{repo} URL. Recommended for a precise dossier. schema: type: string example: oven-sh/bun - name: subreddit in: query required: false description: Optional scope for the Reddit leg (bare name, no r/) — switches it to a subreddit search. schema: type: string - name: include in: query required: false description: CSV subset of dossier,hn,reddit,blogs (default all). Trims which legs run, not the flat price. schema: type: string - name: date_from in: query required: false description: Optional window start (YYYY-MM-DD) applied to the time-bounded legs. schema: type: string - name: date_to in: query required: false description: Optional window end (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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/leads: get: summary: Ranked feed of public conversations where people seek alternatives to or are switching from a competitor. description: "Runs three exact-intent phrases ('alternative to X', 'X vs', 'switching from X') through content_analysis search in parallel, plus a Reddit (sort=new) and a Hacker News leg, then dedupes and intent-ranks them into one feed with a per-lead phrase_matched + intent_score and a counts_by_phrase breakdown. Conversation-level intent only — page-level matching, no author PII harvesting (web leads carry no handle by design). Coverage spine is the three CA legs: <0.5 succeed → 50% refund; all five legs fail → full refund. Deterministic (no LLM); registers cleanly for a recurring-lead-feed monitor." tags: - prism operationId: get_prism_leads security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 50 parameters: - name: competitor in: query required: true description: The competitor/product to mine alternative-seeking conversations for (≤80 chars). schema: type: string example: notion - name: product_category in: query required: false description: Optional disambiguator appended to the social queries to cut cross-domain noise (e.g. 'project management'). schema: type: string example: project management - name: freshness in: query required: false description: Recency floor — Nd/Nw/Nm (e.g. 30d) or an ISO date. Default 30d. schema: type: string example: 30d - name: include in: query required: false description: Set `comments` to attach top-thread Reddit comments to the top leads. schema: type: string - name: limit in: query required: false description: Max leads in the fused feed (1–100, default 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/earned-media: get: summary: A brand's earned-media footprint — news + tech-press + fresh-web clips, deduped and ranked, with an outlet-coverage rollup. description: Fans out content_analysis news search, a Hacker News leg, and a Tavily fresh-news leg in parallel, then dedupes and ranks them into one earned-media clip feed with computed top outlets, freshness labeling (content_analysis fetch_time lags the live web), and — when a `competitor` is supplied — a coverage gap. The content_analysis news leg is the coverage spine (losing it → 50% refund); Hacker News and Tavily are enrichment. `include=digest` adds an LLM narrative summary leg. tags: - prism operationId: get_prism_earned_media security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 25 parameters: - name: brand in: query required: true description: The brand/company to map earned media for. schema: type: string example: Vercel - name: competitor in: query required: false description: Optional competitor for a share-of-coverage gap. schema: type: string example: Netlify - name: date_from in: query required: false description: Window start (YYYY-MM-DD). schema: type: string - name: date_to in: query required: false description: Window end (YYYY-MM-DD). schema: type: string - name: min_domain_rank in: query required: false description: Drop clips from sites below this domain authority. schema: type: integer - name: include in: query required: false description: Set `digest` to add an LLM narrative summary. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/truthsocial-pulse: get: summary: A Truth Social handle's pulse — profile, recent posts, per-post detail drill, and the news echo, in one call. description: Fetches a Truth Social profile + recent posts, drills the top posts for full detail (the F13 post-detail path), and runs a content_analysis news echo for the handle, folded into a deterministic activity/sentiment pulse with stable keys + a methodology_version. The profile leg is critical (404 → full refund); posts/drill/news degrade. No Truth Social search exists upstream — this is handle-scoped. tags: - prism operationId: get_prism_truthsocial_pulse security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: handle in: query required: true description: The Truth Social handle (no @). schema: type: string example: realDonaldTrump - name: drill in: query required: false description: How many top posts to drill for full detail (0 to skip). schema: type: integer example: 5 - name: posts in: query required: false description: How many recent posts to pull (window cap). schema: type: integer - name: news_query in: query required: false description: Override the content_analysis news keyword (defaults to the handle/display name). schema: type: string - name: include in: query required: false description: CSV subset of posts,news to trim which legs run. schema: type: string - name: cursor in: query required: false description: Opaque pagination cursor for the posts leg. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/launch-echo: get: summary: How a launch landed — the Hacker News reaction (top threads + comments), the dev-blog echo, and an optional repo dossier. description: Runs a Hacker News search, digs the top threads' comments, and pulls the dev-blog web echo (content_analysis), with an optional GitHub repo/dossier (explicit `repo=` or auto-resolved from the HN/web hits), folded into a launch-reception snapshot with computed attention + echo + a methodology_version. Comment legs are the coverage spine (<0.5 → 50% refund); a dead HN search → full refund. tags: - prism operationId: get_prism_launch_echo security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: query in: query required: true description: The launch/product name to measure reception for. schema: type: string example: Bun 1.2 - name: repo in: query required: false description: Optional owner/repo or github URL to anchor the dossier. schema: type: string example: oven-sh/bun - name: threads in: query required: false description: How many top HN threads to dig comments for. schema: type: integer - name: date_from in: query required: false description: Window start (YYYY-MM-DD). schema: type: string - name: date_to in: query required: false description: Window end (YYYY-MM-DD). schema: type: string - name: include in: query required: false description: CSV subset toggling the comments/blogs/dossier legs. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/audience-overlap: get: summary: How much two TikTok creators' commenter audiences overlap — Jaccard, shared-fan count, and a confidence label. description: "Samples each creator's recent videos and their commenters, then computes a deterministic audience-overlap: shared commenters, Jaccard index, a/b-only counts, and an honesty `confidence` label (commenters over-index super-fans — a lower bound, never full-audience truth). TikTok-only in v1 (YouTube/Instagram are a fast-follow); a non-tiktok `platform` is rejected. If either creator can't be fetched the overlap is undefined → full refund." tags: - prism operationId: get_prism_audience_overlap security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: handle_a in: query required: true description: First TikTok creator handle. schema: type: string example: mkbhd - name: handle_b in: query required: true description: Second TikTok creator handle. schema: type: string example: mrwhosetheboss - name: platform in: query required: false description: Platform (tiktok only in v1; default tiktok). schema: type: string - name: videos_per_creator in: query required: false description: Recent videos sampled per creator (1–10, default 5) — caps the commenter pull. schema: type: integer - name: depth in: query required: false description: Set `deep` to widen the shared-fan enrichment sample. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/reputation: get: summary: A brand's cross-source reputation — Trustpilot + app stores + Google Business + web sentiment, blended into one weighted score with themed pros/cons. description: Resolves and pulls reviews from Trustpilot, the Google Play + App Store listings, Google Business (and TripAdvisor when `place` is set), plus a content_analysis web-sentiment + rating-distribution read, then blends them into a renormalized weighted composite_score (company vs product axes) with per-source ratings (listed aggregate preferred over sample mean) and an LLM-themed pros/cons pass (counts + verbatim quotes recomputed in code). Coverage spine = the resolved sources (<0.5 → 50% refund; none → full refund); the theme pass degrades to empty without refund. Trustpilot review depth is clamped to 20. tags: - prism operationId: get_prism_reputation security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 30 parameters: - name: brand in: query required: true description: The brand/business/domain to assess. schema: type: string example: Notion - name: sources in: query required: false description: CSV subset of trustpilot,google_play,app_store,google,tripadvisor,web (default the core set). schema: type: string example: trustpilot,google_play,app_store,web - name: country in: query required: false description: Marketplace/locale (DFS location). Defaults to United States. schema: type: string - name: depth in: query required: false description: Reviews per source (Trustpilot clamped ≤20). schema: type: integer - name: place in: query required: false description: Set to enable the place-based legs (Google Business + TripAdvisor). schema: type: string - name: axis in: query required: false description: "Which reputation axis to headline: company, product, or both (default)." schema: type: string enum: - company - product - both - name: app_store_id in: query required: false description: App Store id to anchor that axis directly (skips resolver). schema: type: string - name: google_play_id in: query required: false description: Google Play id to anchor that axis directly (skips resolver). schema: type: string - name: include in: query required: false description: Optional leg toggles. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/employer-brand: get: summary: A company's employer brand — what people say about working there across Reddit, the web, YouTube, Naver, and the company's own LinkedIn voice. description: Fans out a LinkedIn company + posts read (LinkedIn comments are excluded — no upstream endpoint), Reddit search + comment dig, content_analysis news + sentiment, a YouTube search, and Naver blog/cafe, then computes per-surface sentiment plus a posting-tone-vs-reality gap (the company's own LinkedIn voice vs the external chatter). Coverage spine = the requested surfaces (<0.5 → 50% refund; none → full refund); the LLM theme pass degrades without refund. Supply `linkedin_url` to include the LinkedIn axis (omitted silently otherwise). tags: - prism operationId: get_prism_employer_brand security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 30 parameters: - name: company in: query required: true description: The employer/company name. schema: type: string example: Stripe - name: linkedin_url in: query required: false description: The company's LinkedIn URL — enables the LinkedIn voice axis + the posting-vs-reality gap. schema: type: string example: https://www.linkedin.com/company/stripe - name: surfaces in: query required: false description: CSV subset of the surfaces to include. schema: type: string - name: phrases in: query required: false description: Optional extra Reddit search phrases. schema: type: string - name: timeframe in: query required: false description: Reddit timeframe window. schema: type: string - name: date_from in: query required: false description: Window start (YYYY-MM-DD). schema: type: string - name: date_to in: query required: false description: Window end (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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/audience-questions: get: summary: The real questions a topic's audience asks — harvested from Reddit + YouTube threads and clustered by intent (who/what/why/how/vs). description: Searches Reddit and YouTube (and optionally the universal web search) for a topic, extracts question-shaped titles and comments, and LLM-clusters them into labeled intent groups with verbatim quotes and per-question source counts (the model only labels/groups — counts and quotes are recomputed in code). The clustering degrades to one ungrouped cluster on LLM failure (no refund). Coverage spine = the per-source search legs (<0.5 → 50% refund; all dead → full refund). Great for content/SEO briefs and FAQ generation. tags: - prism operationId: get_prism_audience_questions security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 30 parameters: - name: topic in: query required: true description: The topic/keyword to mine audience questions for. schema: type: string example: kubernetes operators - name: platforms in: query required: false description: CSV subset of reddit,youtube,web (default reddit,youtube). schema: type: string example: reddit,youtube - name: max_questions in: query required: false description: Cap on questions returned. schema: type: integer - name: threads_per_source in: query required: false description: How many top threads to dig per source. schema: type: integer - name: timeframe in: query required: false description: Recency window. schema: type: string - name: include in: query required: false description: Set `web` to add the universal-search leg. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/product-reviews: get: summary: A product's reviews across Amazon + Google Shopping + Trustpilot, folded into a cross-marketplace rating + themed pros/cons report. description: Resolves a product on Amazon (ASIN) + Google Shopping (gid) + Trustpilot and pulls each source's reviews, folded into a per-source rating summary (listed aggregate preferred over sample mean), a retailer matrix, and an LLM topic pass with per-topic rating impact (the model only assigns review ids — averages are recomputed in code). Anchor with `asin`/`gid` for precision (the gid is `product.ext.gid`, NOT the catalogid) or `query` to auto-resolve. Coverage spine = the resolved sources (<0.5 → 50% refund; none → full refund). Commerce legs take 20-60s. tags: - prism operationId: get_prism_product_reviews security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 30 x-socialcrawl-oneOf: - - query - asin - gid parameters: - name: query in: query required: false description: "Product name to auto-resolve across marketplaces. (one of: query, asin, gid — at least one required)" schema: type: string example: AirPods Pro 3 - name: asin in: query required: false description: "Amazon ASIN to anchor the Amazon axis directly. (one of: query, asin, gid — at least one required)" schema: type: string - name: gid in: query required: false description: "Google product id (gid) to anchor the Google Shopping axis (NOT the catalogid). (one of: query, asin, gid — at least one required)" schema: type: string - name: sources in: query required: false description: CSV subset of amazon,google_shopping,trustpilot (default all). schema: type: string example: amazon,google_shopping,trustpilot - name: country in: query required: false description: Marketplace country (DFS location). schema: type: string - name: depth in: query required: false description: Reviews per source (Trustpilot clamped ≤20). schema: type: integer - name: competitors in: query required: false description: Optional competitor products for a comparison (validated; deeper sweep is a fast-follow). schema: type: string - name: include in: query required: false description: Optional leg toggles. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/apps-lookup: get: summary: One app across Google Play + the App Store — resolved, title-matched, and compared into a cross-store rating + listing report. description: "Resolves an app on both stores (by `title`, or directly via `google_play_id`/`app_store_id`), applies a title + developer match guard so two same-named-but-different apps aren't conflated, and folds the two listings into a cross-store comparison: per-store rating + install + price, the rating gap, and a match confidence. A clean no-match across stores is a valid (fully-charged) result; if neither store resolves the title → 404 + refund; both stores dead → full refund." tags: - prism operationId: get_prism_apps_lookup security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 30 x-socialcrawl-oneOf: - - title - google_play_id - app_store_id parameters: - name: title in: query required: false description: "The app title to resolve across both stores. (one of: title, google_play_id, app_store_id — at least one required)" schema: type: string example: Notion - name: google_play_id in: query required: false description: "Google Play app id to anchor that store directly. (one of: title, google_play_id, app_store_id — at least one required)" schema: type: string - name: app_store_id in: query required: false description: "App Store app id to anchor that store directly. (one of: title, google_play_id, app_store_id — at least one required)" schema: type: string - name: stores in: query required: false description: CSV subset of google_play,app_store (default both). schema: type: string example: google_play,app_store - name: country in: query required: false description: Store country. schema: type: string - name: language in: query required: false description: Store language. schema: type: string - name: match_threshold in: query required: false description: Title-similarity threshold for the cross-store match guard (0–1, default 0.6). schema: type: string - name: include in: query required: false description: Optional leg toggles. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/org-radar: get: summary: A GitHub org's footprint — its top repos each expanded into a full dossier (releases, issue load, top request/complaint), rolled up. description: "Lists a GitHub org's repositories, picks the top N by stars (forks/archived filtered), and runs the repo/dossier composite on each in parallel, folded into an org-level rollup. Metered: 1cr to resolve the org + 5cr per repo dossiered; the unused per-repo credits are refunded down to the dossiers that actually succeeded. The org repo-list leg is critical (unknown org → 404 + full refund)." tags: - prism operationId: get_prism_org_radar security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 26 parameters: - name: org in: query required: true description: The GitHub org login or a github.com/{org} URL. schema: type: string example: vercel - name: repos in: query required: false description: How many top repos to dossier (1–10, default 5) — drives the metered price. schema: type: integer example: 5 - name: sort in: query required: false description: "Repo ranking: stars (default), updated, or pushed." schema: type: string enum: - stars - updated - pushed - name: include in: query required: false description: Optional leg toggles. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/creator-vet: get: summary: Vet a creator before partnering — engagement quality, commenter authenticity, posting cadence, and controversy signals, optionally across platforms. description: "Pulls a creator's profile + recent posts + a commenter sample (TikTok / YouTube / Instagram) plus a news + Reddit + Hacker News controversy read, and computes deterministic authenticity signals: engagement rate, a low-quality-commenter share, posting cadence, and controversy inputs. `include=cross_platform` adds the universal cross-platform presence leg (+25cr, refunded if it fails). The core profile leg is critical (creator not found → full refund)." tags: - prism operationId: get_prism_creator_vet security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 50 parameters: - name: handle in: query required: true description: The creator handle to vet. schema: type: string example: mkbhd - name: platform in: query required: false description: Primary platform (tiktok/youtube/instagram). schema: type: string example: youtube - name: depth in: query required: false description: Set `deep` to widen the post + commenter sample. schema: type: string - name: include in: query required: false description: Set `cross_platform` to add the universal cross-platform presence leg (+25cr). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/korea-gap: get: summary: What the world is talking about that Korea isn't (and vice versa) — the global vs Korean (Naver) conversation gap for a brand/topic. description: "Fans the Korean Naver corpora (news/blog/cafe/kin/shop/web) against the global conversation (the universal /search/everywhere leg) and computes a directional presence gap: which surface over-indexes the topic, a per-channel Korean map, and a translated quote sample (KR→EN, soft LLM). Metered 40cr full; `include` without `social` drops the everywhere leg for the 15cr web-only variant. Korean volume is a directional per-surface presence index (item-count-bounded), not absolute counts." tags: - prism operationId: get_prism_korea_gap security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 40 parameters: - name: query in: query required: true description: The brand/topic to compare across the global and Korean conversations. schema: type: string example: Stanley cup - name: include in: query required: false description: Members include `social` (the everywhere leg) + `digest`. Drop `social` for the 15cr web-only variant. schema: type: string example: social,digest - name: date_from in: query required: false description: Window start (YYYY-MM-DD). schema: type: string - name: date_to in: query required: false description: Window end (YYYY-MM-DD). schema: type: string - name: display in: query required: false description: Naver results per corpus. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/share-of-voice: get: summary: Engagement-weighted Share of Voice across 2-5 brands, with web+social split, emotion overlay, and ESOV. description: Per brand, fans out to content_analysis summary/phrase-trends/sentiment plus /search/everywhere (consuming the real per-platform items_by_source counts, not the capped fused list), then computes a published-formula SOV (web + social, equal-weighted by default), optional true-share-of-category (numeric `category_code`), and ESOV (`market_shares`, Binet/Field — a planning signal, not a growth guarantee). Metered at 40cr/brand (20 web-only); a brand whose social search half-failed is automatically cheaper, with the reason legible in `legs[]` + per-brand `coverage`. tags: - prism operationId: get_prism_share_of_voice security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 40 parameters: - name: brands in: query required: true description: 2-5 competitor brand names (CSV). schema: type: string example: notion,coda,airtable - name: category_code in: query required: false description: Numeric DFS taxonomy code for true-share-of-category (use content_analysis/categories to look one up). schema: type: string - name: market_shares in: query required: false description: JSON map of real market share per brand (fraction or %), e.g. {"notion":0.4,"coda":0.25,"airtable":0.35}, to compute ESOV. schema: type: string - name: include in: query required: false description: CSV toggles (default `emotions,social`). Drop `social` for the cheaper web-only variant; drop `emotions` to skip the sentiment leg. schema: type: string example: social,emotions - name: page_type in: query required: false description: Optional surface filter forwarded to the content_analysis legs. schema: type: string enum: - ecommerce - news - blogs - message-boards - organization - name: date_from in: query required: false description: Window start (YYYY-MM-DD). Defaults to 90 days ago. schema: type: string - name: date_to in: query required: false description: Window end (YYYY-MM-DD). Defaults to today. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/review-integrity: get: summary: Cross-source review integrity verdict (statistical, deterministic). description: "Computes a documented, reproducible integrity grade for a product or brand by comparing ratings across Amazon, Google Shopping, Trustpilot, and the open web: cross-source rating divergence (Welch t-test), web-distribution bimodality (Sarle's coefficient), unsolicited-forum tone contrast, and spam-domain clustering. No AI/LLM — every number is a published formula (`methodology_version`). Returns the grade, per-signal evidence, per-source ratings, the divergence pair, and the raw sampled reviews. Reviewer-history tests are flagged `unavailable` (no upstream reviewer-profile source). Anchor on `asin`/`gid` for precision or `query` to auto-resolve. Commerce data takes 20-60s." tags: - prism operationId: get_prism_review_integrity security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 30 x-socialcrawl-oneOf: - - query - asin - gid parameters: - name: query in: query required: false description: "Product or brand name to evaluate. (one of: query, asin, gid — at least one required)" schema: type: string example: AirPods Pro 3 - name: asin in: query required: false description: "Amazon ASIN to anchor the Amazon axis directly (skips product-search). (one of: query, asin, gid — at least one required)" schema: type: string - name: gid in: query required: false description: "Google product id (gid) to anchor the Google Shopping axis (NOT the catalogid product.id). (one of: query, asin, gid — at least one required)" schema: type: string - name: sources in: query required: false description: CSV subset of amazon,google_shopping,trustpilot,web,forums (default all). schema: type: string example: amazon,trustpilot,forums - name: country in: query required: false description: Marketplace country (DFS location). Defaults to United States. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/answers: get: summary: "Multi-engine AI consensus: one question → Perplexity + Grok + Tavily answers verbatim, merged citations, and an agreement matrix." description: "Fans your question to multiple AI engines in parallel and keeps each answer verbatim, merges + dedupes their citations by normalized URL (with a `cited_by` list), and computes where they agree and disagree: a pairwise `agreement_matrix` + `disputed_claims` (the one labeled LLM step — degrades to null on failure) plus a deterministic `citation_overlap` (Jaccard, hand-verifiable). The second-opinion API for agents — one question, one bounded-cost call. Streams each engine's answer as it settles (SSE). `include=polymarket` adds probabilistic-market grounding. 15cr flat; a strict-majority engine failure refunds half (the raw answers are always the floor value)." tags: - prism operationId: get_prism_answers security: - ApiKeyAuth: [] x-credit-tier: premium x-credit-cost: 15 parameters: - name: query in: query required: true description: The question, forwarded verbatim to every engine. schema: type: string example: will the fed cut rates in september - name: engines in: query required: false description: CSV subset of perplexity,grok,tavily (default all three). schema: type: string - name: include in: query required: false description: "CSV of optional grounding legs: `polymarket` adds market probabilities (trimmed)." schema: type: string example: polymarket - name: Cache-Control in: header required: false description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details. schema: type: string example: no-cache - name: Idempotency-Key in: header required: false description: Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL. schema: type: string example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the request succeeded example: true platform: type: string description: Platform name example: tiktok endpoint: type: string description: API endpoint path example: /v1/tiktok/profile data: type: object description: Platform-specific response data properties: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/video-intel: get: summary: One video URL → detail + stats + transcript + top comments + commenter sample, across YouTube/TikTok/Rumble/Instagram. description: Fans out the video detail, comments, an optional transcript (10cr, never charged when the video has none), and ≤3 commenter profiles, folding them into one unified payload. Every leg joins on the same video `url`. Sync by default; streams Server-Sent Events when `include=transcript` (the transcript leg can take 20s+). `legs[]` reports each fired leg's status, cost, and latency; `coverage` + `partial_failure` flag any degraded leg. Commenter profiles ship for TikTok + Instagram in v1. tags: - prism operationId: get_prism_video_intel security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 5 parameters: - name: url in: query required: true description: Absolute http(s) URL of a YouTube, TikTok, Rumble, or Instagram video. schema: type: string example: https://www.youtube.com/watch?v=dQw4w9WgXcQ - name: comments in: query required: false description: How many top comments to fetch (0–50, default 20). `0` skips the comments leg. schema: type: string - name: include in: query required: false description: "CSV of optional costed legs: `transcript` (adds the dedicated transcript leg, +10cr, refunded when null) and/or `commenter_profiles` (≤3 commenter mini-profiles, TikTok/Instagram in v1)." schema: type: string example: transcript,commenter_profiles - name: Cache-Control in: header required: false description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details. schema: type: string example: no-cache - name: Idempotency-Key in: header required: false description: Optional UUID that makes the request safely retriable. A replay returns the original response verbatim and deducts 0 new credits. Scoped per account with a 24-hour TTL. schema: type: string example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean description: Whether the request succeeded example: true platform: type: string description: Platform name example: tiktok endpoint: type: string description: API endpoint path example: /v1/tiktok/profile data: type: object description: Platform-specific response data properties: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/voice: get: summary: One person's public posts across X, Threads, Bluesky, and Truth Social, time-merged. description: Fetches a handle's recent posts from four microblogs in parallel, time-merges them into one chronological feed, and computes platform presence, a cross-post rate, and a per-platform tone label (a soft `gpt-5.4-nano` heuristic that degrades to absent on failure). Microblogs the handle isn't on return empty arrays with `platform_presence:false` — the absence map is the product. Flat 5cr; all-miss → full refund. The `legs[]` block reports each leg's status, cost, and latency. v1 is list-level (no per-post detail drill). tags: - prism operationId: get_prism_voice security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 5 parameters: - name: handle in: query required: true description: The handle to look up across all four microblogs (a single leading @ is stripped). schema: type: string example: nasa - name: platforms in: query required: false description: CSV subset of twitter,threads,bluesky,truthsocial (default all four). schema: type: string example: twitter,threads,bluesky,truthsocial - name: cursor in: query required: false description: Opaque per-platform pagination token from a prior response's cursors_by_platform (twitter is a single non-paginatable page). schema: type: string - name: include in: query required: false description: CSV subset of posts_by_platform,merged_timeline,computed to trim the payload (posts_by_platform is always returned). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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/brief: get: summary: One query across the Korean internet (6 Naver corpora) + optional digest. description: Fans a single query across Naver News, Blog, Café (community), 지식iN (Q&A), Shopping, and the Korean web index in parallel, returning each corpus's raw items with the original Korean preserved, plus a volume-by-corpus map, top recent blogs, and a shopping price range. Add `include=digest` for an English translated synthesis with pull-quotes. The Korea-market brief no western data vendor can produce — all six corpora are native Naver. Paginate each corpus via the opaque `cursor`. Flat 10cr; coverage-based partial refund when a majority of corpora fail. tags: - naver - prism operationId: get_naver_brief security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 10 parameters: - name: query in: query required: true description: Search query (Korean or any language). schema: type: string example: 삼성전자 - name: corpora in: query required: false description: CSV subset of news,blog,cafearticle,kin,shop,webkr (default all six). schema: type: string example: news,blog,shop - name: display in: query required: false description: Items per corpus (1–100, default 20). schema: type: integer - name: start in: query required: false description: 1-indexed offset per corpus (1–1000, default 1). Prefer `cursor` for paging. schema: type: integer - name: sort in: query required: false description: sim (relevance, default) or date; shop also asc/dsc (price); kin also point. schema: type: string - name: include in: query required: false description: Set to `digest` for an LLM English digest with translated quotes. schema: type: string - name: cursor in: query required: false description: Opaque pagination token from a prior response's next_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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/app-reviews: get: summary: Cross-store app review intelligence (Google Play + App Store) — translated, clustered, sentiment-scored. description: "One call returns a topic-clustered, sentiment-classified review report across Google Play and the App Store: per-store rating summary (listed aggregate), topic clusters, a pooled daily sentiment timeline, extracted feature requests, and developer-response rate — plus every raw review on the shared canonical Review shape. Resolve by store app_id (com.spotify.music / 324684580) or by `query` to auto-resolve the top app on each requested store. Sync by default; streams Server-Sent Events when the client sends `Accept: text/event-stream` (the DFS review legs + clustering run ~30s). Single-store calls are 10 credits; both stores 15." tags: - prism operationId: get_prism_app_reviews security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 15 parameters: - name: google_play_id in: query required: false description: Google Play package name (e.g. com.spotify.music). schema: type: string - name: app_store_id in: query required: false description: App Store numeric app id (e.g. 324684580). schema: type: string - name: query in: query required: false description: App name to auto-resolve the top hit on each requested store (when no id is given). schema: type: string example: spotify - name: country in: query required: false description: Storefront country (DFS location name or numeric code). Defaults to the DFS default location. schema: type: string - name: language in: query required: false description: Language code (e.g. en). schema: type: string - name: depth in: query required: false description: Reviews per store (default 150 Google / 50 Apple, max 600). The App Store returns ~50 at depth 40. schema: type: integer example: 150 - name: stores in: query required: false description: CSV subset of google_play,app_store. Defaults to whichever ids/query resolve. schema: type: string - name: include in: query required: false description: CSV of topics,sentiment_timeline,feature_requests,responses (default all). Omitting topics+feature_requests skips the LLM step. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/creator-card: get: summary: One handle, unified author cards across TikTok, Instagram, YouTube, X (and more). description: Looks up a single handle across multiple platforms in parallel and returns one unified author card per platform — followers, verified flag, bio, ids — with null for the platforms the handle isn't found on, plus combined follower totals and an any-verified flag. The default set is TikTok, Instagram, YouTube, and Twitter; Threads, Bluesky, and Truth Social can be added via `platforms`. A handle existing on only some platforms is a successful, complete answer (the nulls are the product); only an all-platform miss refunds. Flat 5 credits for up to 4 platforms, +1 credit per extra platform. `legs[]` reports each platform leg's status, cost, and latency. tags: - prism operationId: get_prism_creator_card security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 5 parameters: - name: handle in: query required: true description: The handle to look up across every requested platform (a single leading @ is stripped). schema: type: string example: mrbeast - name: platforms in: query required: false description: CSV subset of tiktok,instagram,youtube,twitter,threads,bluesky,truthsocial (default the first four). Unknown platforms are ignored. schema: type: string example: tiktok,instagram,youtube,twitter - name: include in: query required: false description: CSV subset of cards,totals to trim the payload (cards is always returned). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/handle-audit: get: summary: Should you pull this handle? One call scores a handle across platforms, ranks the best ones, and projects the data volume + credit cost to pull it. description: "Answers three questions BEFORE you spend credits on a full pull. (1) Is this handle worth pulling? — a deterministic 0-100 composite quality score with five component sub-scores (presence, audience, engagement, activity, content_richness). (2) On which platforms? — a per-platform verdict and a `best_platforms` ranking, plus the native endpoints to hit next, so you can route the follow-up pull. (3) How much data is there? — a `surface` block projecting post + comment volume and the credit cost to pull it. Looks a single handle up across TikTok, Instagram, YouTube, and X in parallel (Threads/Bluesky/Truth Social can be added via `platforms`); for every platform the handle is found on it also samples recent posts to measure engagement and posting activity. A handle found on only some platforms is a successful, complete answer (the misses are the product); only an all-platform miss refunds. The call returns within a bounded latency budget: a slow upstream platform is skipped rather than stalling the whole audit, and the score is computed from the data available at request time (a skipped or profile-only platform is scored on the signals that did return and shown in `legs[]`, never silently dropped or penalized as a miss). Data completeness is first-class in the contract: `confidence` reports a deterministic high/medium/low tier with the reason, `evaluated_platforms`/`skipped_platforms` name exactly which platforms answered, `computed_at` timestamps the computation (cached responses can be up to 30 minutes old), and `score_version` pins the scoring-model semver so stored scores stay comparable across tuning releases. Scores are advisory heuristics estimated from public data at request time, not calibrated probabilities. Flat 5 credits for up to 4 platforms, +1 credit per extra platform. `legs[]` reports each leg's status, cost, and latency. See `prism/creator-vet` for the deeper 'should I sponsor' report." tags: - prism operationId: get_prism_handle_audit security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 5 parameters: - name: handle in: query required: true description: The handle to audit across every requested platform. Accepts a bare handle, a leading @, or a full profile URL (the platform is sniffed from the host). schema: type: string example: mrbeast - name: platforms in: query required: false description: CSV subset of tiktok,instagram,youtube,twitter,threads,bluesky,truthsocial (default the first four). Unknown platforms are ignored. Max 8. schema: type: string example: tiktok,instagram,youtube,twitter - name: sample in: query required: false description: Recent posts sampled per found platform for the engagement + activity metrics (default 10, max 25). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /prism/post-stats: post: summary: Up to 100 mixed-platform post URLs → current engagement per URL, failed URLs refunded. description: "Bulk stats refresh for verification loops (clipper payouts). POST a JSON body with a `urls` array (1–100 mixed-platform post links); returns one row per URL — platform, status (ok / not_found / error / unsupported), the unified engagement block (views/likes/comments/shares/saves), and a server `fetched_at` timestamp — in input order. Per-URL isolation: one dead link never fails the batch. Metered at 1 credit per successful URL; dead, errored, and unsupported URLs are refunded, so you pay exactly for the counts you got. Never cached (every call reads the live count). Optionally streams Server-Sent Events when the client sends `Accept: text/event-stream`." tags: - prism operationId: post_prism_post_stats 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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 prism/post-stats. Required: urls." content: application/json: schema: type: object properties: urls: type: array items: type: string include: type: string required: - urls /prism/comment-lookup: post: summary: Re-check up to 25 known comments in one call — per-item results, failed items refunded. description: "Batch version of the single-comment lookup, built for recurring brand-comment tracking. Pass up to 25 items, each either `{ comment_url }` or `{ platform, post_url, comment_id }` (plus optional `parent_comment_id`, `position_hint`, `deep_scan`). Every item resolves independently — one bad item never fails the batch — and returns a `status` of `found`, `not_found`, `error`, or `deferred`. Billing is per item (TikTok 2 credits, Instagram 5 credits; deep_scan raises it); only `found` items are charged, everything else is refunded, and the whole batch holds at most 100 credits. Store each returned `lookup.position_hint` and pass it back on the next run so a daily refresh of your tracked comments costs ~1-2 credits per item. Returns sync JSON, or a typed SSE stream (`Accept: text/event-stream`) that emits each item as it settles. Items not started within the 45-second budget come back `deferred` (refunded) — just re-request them." tags: - prism operationId: post_prism_comment_lookup security: - ApiKeyAuth: [] x-credit-tier: standard x-credit-cost: 2 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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 prism/comment-lookup. Required: items." content: application/json: schema: type: object properties: items: type: string required: - items /prism/profiles: post: summary: Up to 50 (platform, handle) pairs → one canonical Author per row, failed handles refunded. description: "Batch profile lookup for handle vetting. POST a JSON body with an `items` array of 1–50 `{ platform, handle, custom_id? }` objects (handle accepts an @handle, a bare handle, or a pasted profile URL); returns one row per item — the canonical Author object (same shape as the single GET profile endpoint), a `status` of ok / not_found / unsupported / error / deferred, the caller's `custom_id` echoed, and the credits that row cost — in input order. Per-item isolation: one dead or private handle never fails the batch. Billing is per item at each platform's own credit tier (most platforms 1 credit; LinkedIn 5); only successful rows are charged, everything else is refunded. Supported platforms: instagram, tiktok, youtube, twitter, threads, twitch, snapchat, truthsocial, bluesky, kwai, linkedin, facebook. Never cached. Optionally streams Server-Sent Events when the client sends `Accept: text/event-stream`." tags: - prism operationId: post_prism_profiles 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for 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 prism/profiles. Required: items." content: application/json: schema: type: object properties: items: type: string required: - items /content_analysis/search: get: summary: Search web citations of a keyword with per-mention sentiment description: Returns paginated web citations (news, blogs, ecommerce, message-boards, organization pages) that mention the keyword, each scored on a 6-axis emotional sentiment model (anger, happiness, love, sadness, share, fun) plus positive/negative/neutral connotation probabilities. This is web-wide brand listening over DataForSEO's citation database — page-level mentions, not native platform posts. Cursor-paginated via `cursor`; `total` is the global match count, not the page size. tags: - content_analysis operationId: get_content_analysis_search security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: keyword in: query required: true description: Brand or term to find mentions of. Wrap in escaped double-quotes for an exact phrase (e.g. "logitech mouse"). schema: type: string example: openai - name: page_type in: query required: false description: "Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. Translated to a page_types filter upstream." schema: type: string enum: - ecommerce - news - blogs - message-boards - organization - name: search_mode in: query required: false description: as_is (default) returns every matching page; one_per_domain dedupes to the top page per domain. schema: type: string enum: - as_is - one_per_domain example: as_is - name: limit in: query required: false description: Number of citations to return per page (1–100, default 10). Paginate via `cursor` for more. schema: type: integer example: 10 - name: cursor in: query required: false description: Opaque pagination cursor — pass the `next_cursor` from the previous response to fetch the next page. schema: type: string - name: order_by in: query required: false description: Sort rules as "field,direction"; separate multiple rules with ";" (e.g. content_info.sentiment_connotations.anger,desc). schema: type: string - name: filters in: query required: false description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions). Combined with page_type via AND when both are present. 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/summary: get: summary: Aggregate mention summary for a keyword description: "Returns a single roll-up over every web citation of the keyword: total mention count, top domains, sentiment-connotation totals, positive/negative/neutral splits, top text + page categories, and breakdowns by page type, country, and language. The fastest way to size and characterize a brand's web-wide footprint in one call." tags: - content_analysis operationId: get_content_analysis_summary security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: keyword in: query required: true description: Brand or term to summarize. schema: type: string example: openai - name: page_type in: query required: false description: "Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization." schema: type: string enum: - ecommerce - news - blogs - message-boards - organization - name: positive_connotation_threshold in: query required: false description: Minimum positive-connotation probability (0–1, default 0.4) for a mention to count as positive. schema: type: string - name: sentiments_connotation_threshold in: query required: false description: Minimum sentiment-connotation probability (0–1, default 0.4) for the 6-axis emotion buckets. schema: type: string - name: internal_list_limit in: query required: false description: Cap on internal arrays such as top_domains / categories (1–20). schema: type: integer - name: filters in: query required: false description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/sentiment: get: summary: Sentiment breakdown for a keyword description: "Returns two sentiment distributions for the keyword's web mentions: a positive/negative/neutral split (each a full summary sub-object) and a 6-axis emotional split (anger, happiness, love, sadness, share, fun — each a full summary sub-object). Sentiment is DataForSEO's model-derived NLP, passed through verbatim — not ground truth." tags: - content_analysis operationId: get_content_analysis_sentiment security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: keyword in: query required: true description: Brand or term to analyze. schema: type: string example: openai - name: page_type in: query required: false description: "Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization." schema: type: string enum: - ecommerce - news - blogs - message-boards - organization - name: positive_connotation_threshold in: query required: false description: Minimum positive-connotation probability (0–1, default 0.4). schema: type: string - name: filters in: query required: false description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/rating-distribution: get: summary: Rating histogram for a keyword description: Returns a 10-bucket histogram (0.0–0.1 … 0.9–1.0) of the relative ratings found across web mentions of the keyword. Each bucket carries a full summary sub-object (total_count, top_domains, sentiment, categories, page types, countries, languages) so you can see how sentiment and sources vary with rating. Best for products and review-heavy terms. tags: - content_analysis operationId: get_content_analysis_rating_distribution security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: keyword in: query required: true description: Product or term to build the rating histogram for. schema: type: string example: iphone - name: page_type in: query required: false description: "Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization." schema: type: string enum: - ecommerce - news - blogs - message-boards - organization - name: filters in: query required: false description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/phrase-trends: get: summary: Keyword mention volume + sentiment over time description: Returns a time series (one row per day/week/month bucket) of mention volume and sentiment for the keyword over a date range. Each row is a full summary sub-object (total_count, sentiment, top domains, categories…). Track how a brand's web-wide mentions and sentiment move over time. tags: - content_analysis operationId: get_content_analysis_phrase_trends security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: keyword in: query required: true description: Brand or term to trend. schema: type: string example: openai - name: date_from in: query required: true description: Start of the date range (yyyy-mm-dd). schema: type: string example: 2025-01-01 - name: date_to in: query required: false description: End of the date range (yyyy-mm-dd); defaults to today. schema: type: string - name: date_group in: query required: false description: "Bucket size: day, week, or month (default month)." schema: type: string enum: - day - week - month example: month - name: page_type in: query required: false description: "Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization." schema: type: string enum: - ecommerce - news - blogs - message-boards - organization - name: internal_list_limit in: query required: false description: Cap on internal arrays per bucket (1–20). schema: type: integer - name: filters in: query required: false description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/category-trends: get: summary: Category mention volume + sentiment over time description: "Like phrase-trends, but keyed on a category code from the /content_analysis/categories taxonomy instead of a keyword. Returns a time series of mention volume and sentiment for an entire content category (e.g. Apparel) over a date range. Note the different mental model: this trends a category, not a brand term." tags: - content_analysis operationId: get_content_analysis_category_trends security: - ApiKeyAuth: [] x-credit-tier: advanced x-credit-cost: 20 parameters: - name: category_code in: query required: true description: Numeric category code from the /content_analysis/categories taxonomy (e.g. 10021 = Apparel). schema: type: string example: "10021" - name: date_from in: query required: true description: Start of the date range (yyyy-mm-dd). schema: type: string example: 2025-01-01 - name: date_to in: query required: false description: End of the date range (yyyy-mm-dd); defaults to today. schema: type: string - name: date_group in: query required: false description: "Bucket size: day, week, or month (default month)." schema: type: string enum: - day - week - month example: month - name: internal_list_limit in: query required: false description: Cap on internal arrays per bucket (1–20). schema: type: integer - name: filters in: query required: false description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions). 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/languages: get: summary: List supported Content Analysis languages description: Returns the list of languages (name + ISO code) supported by the Content Analysis endpoints. Static reference data — use the codes to filter or interpret the `language` field on mentions. Heavily cached. tags: - content_analysis operationId: get_content_analysis_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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/locations: get: summary: List supported Content Analysis locations description: Returns the list of locations supported by the Content Analysis endpoints. Static reference data — use it to interpret the `country` field on mentions. Heavily cached. tags: - content_analysis operationId: get_content_analysis_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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/categories: get: summary: List the Content Analysis category taxonomy description: "Returns the full content-category taxonomy (3,000+ nodes: category_code, category_name, parent code) used by Content Analysis. Use it to look up a `category_code` for the category-trends endpoint and to decode the numeric `text_category` arrays on mentions. Heavily cached." tags: - content_analysis operationId: get_content_analysis_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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /content_analysis/filters: get: summary: List the filterable fields for Content Analysis description: Returns the map of filterable fields → value types (str, num, time, array.num, array.str) accepted by the advanced `filters` param on the search/summary/sentiment endpoints. Use it to build valid filter expressions. Heavily cached. tags: - content_analysis operationId: get_content_analysis_filters 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: *a16 credits_used: type: integer description: Number of credits consumed example: 1 credits_remaining: type: integer description: Credits remaining on your account example: 4999 request_id: 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: *a34 "400": description: Invalid request — missing or malformed parameters x-error-codes: *a2 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INVALID_REQUEST message: Invalid request — missing or malformed parameters status: 400 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "401": description: Unauthorized — missing or invalid API key x-error-codes: *a3 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: MISSING_API_KEY message: Unauthorized — missing or invalid API key status: 401 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "402": description: Insufficient credits — purchase more to continue x-error-codes: *a4 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INSUFFICIENT_CREDITS message: Insufficient credits — purchase more to continue status: 402 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "404": description: Not found — the endpoint does not exist, or the requested resource was not found upstream x-error-codes: *a5 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: ENDPOINT_NOT_FOUND message: Not found — the endpoint does not exist, or the requested resource was not found upstream status: 404 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "405": description: Method not allowed — wrong HTTP verb for this endpoint x-error-codes: *a6 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: METHOD_NOT_ALLOWED message: Method not allowed — wrong HTTP verb for this endpoint status: 405 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "409": description: Idempotency conflict — a request with this Idempotency-Key is still in flight x-error-codes: *a7 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_CONFLICT message: Idempotency conflict — a request with this Idempotency-Key is still in flight status: 409 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "413": description: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" x-error-codes: *a8 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: PAYLOAD_TOO_LARGE message: "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing" status: 413 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "422": description: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload x-error-codes: *a9 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: IDEMPOTENCY_KEY_PAYLOAD_MISMATCH message: Idempotency payload mismatch — this Idempotency-Key was already used with a different request payload status: 422 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "429": description: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. x-error-codes: *a10 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: CONCURRENCY_LIMIT message: Concurrency limit exceeded — too many simultaneous requests. Carries a `Retry-After` header (seconds) plus `X-Concurrency-Limit`/`X-RateLimit-Limit` and `X-Concurrency-Remaining`/`X-RateLimit-Remaining` (these limit + remaining headers are emitted on every response, not just the 429). Honor `Retry-After`, then back off exponentially with jitter. See /docs/rate-limits. status: 429 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "500": description: Internal server error — credits automatically refunded x-error-codes: *a11 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: INTERNAL_ERROR message: Internal server error — credits automatically refunded status: 500 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "502": description: Upstream error — the platform returned an error, credits refunded x-error-codes: *a12 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: UPSTREAM_ERROR message: Upstream error — the platform returned an error, credits refunded status: 502 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 "503": description: Service unavailable — circuit breaker open for this platform, credits refunded x-error-codes: *a13 content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: success: false error: type: SERVICE_UNAVAILABLE message: Service unavailable — circuit breaker open for this platform, credits refunded status: 503 doc_url: https://www.socialcrawl.dev/docs/errors credits_used: 0 credits_remaining: null request_id: req_abc123 /credits/balance: get: summary: Check your credit balance description: Returns the current credit balance and the number of deduction transactions in the trailing 24 hours. Metadata call — costs 0 credits and never hits upstream platforms. tags: - meta operationId: meta_credits_balance security: - ApiKeyAuth: [] x-credit-tier: standard parameters: [] responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean example: true platform: type: string example: meta endpoint: type: string example: /v1/credits/balance data: type: object properties: balance: type: integer example: 4999 recent_deductions: type: integer example: 12 required: - balance - recent_deductions credits_used: type: integer example: 0 credits_remaining: type: integer example: 4999 request_id: type: string cached: type: boolean example: false "401": description: Unauthorized — missing or invalid API key /credits/transactions: get: summary: List your credit transactions description: Returns your credit ledger (deductions negative, refunds positive) as dispute-grade receipts, newest first. Cursor-paginated and filterable by request_id. Metadata call — costs 0 credits and never hits upstream platforms. tags: - meta operationId: meta_credits_transactions security: - ApiKeyAuth: [] x-credit-tier: standard parameters: - name: limit in: query required: false description: Page size. Defaults to 50, capped at 100. schema: type: integer minimum: 1 maximum: 100 example: 50 - name: cursor in: query required: false description: Opaque pagination cursor from a previous response's next_cursor. A malformed cursor starts from the top. schema: type: string - name: request_id in: query required: false description: Return only the receipt(s) for a single request_id (exact match). schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean example: true platform: type: string example: meta endpoint: type: string example: /v1/credits/transactions data: type: object properties: items: type: array items: type: object properties: id: type: string type: type: string enum: - purchase - deduction - refund - bonus amount: type: integer example: -20 balance_after: type: integer example: 4980 description: type: - string - "null" endpoint: type: - string - "null" platform: type: - string - "null" credit_tier: type: - string - "null" enum: - standard - advanced - premium - null request_id: type: - string - "null" created_at: type: string format: date-time required: - id - type - amount - balance_after - created_at next_cursor: type: - string - "null" required: - items - next_cursor credits_used: type: integer example: 0 credits_remaining: type: integer example: 4980 request_id: type: string cached: type: boolean example: false "401": description: Unauthorized — missing or invalid API key /status: get: summary: Platform status & circuit state description: Returns the operational status of every upstream platform (derived from the circuit breaker), the current upstream-version distribution, and a timestamp. Public meta route — no API key, no credit cost, no upstream call. Use it to check a platform's health before retrying persistent 502s. tags: - meta operationId: meta_status security: [] x-credit-tier: standard parameters: [] responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - operational - degraded example: operational description: Overall API status across all platforms. platforms: type: object additionalProperties: type: object properties: status: type: string enum: - operational - degraded - down description: Per-platform status keyed by platform name (operational / degraded / down). upstreamVersions: type: object additionalProperties: true description: Current upstream-version distribution (RTG-02) — lets operators track drift as upstreams deprecate versions. updated_at: type: string format: date-time description: When this status snapshot was generated. required: - status - platforms - updated_at x-tagGroups: - name: Account tags: - meta - name: Universal Search tags: - search - ai-search - geo - name: Prism — Composite Intelligence tags: - prism - name: Social Platforms tags: - tiktok - instagram - youtube - facebook - facebook-ads - twitter - linkedin - linkedin-ads - reddit - threads - pinterest - twitch - truthsocial - snapchat - kick - bluesky - rumble - kwai - name: Commerce & Reviews tags: - amazon - tiktokshop - app_store - google_play - google_shopping - trustpilot - tripadvisor - name: Search, News & Web tags: - google - google-ads - google_news - google_finance - naver - perplexity - tavily - hackernews - github - content_analysis - polymarket - spotify - name: Link in Bio tags: - linktree - komi - pillar - linkbio - linkme - name: More Platforms tags: - google_trends - web - name: Utility tags: - utility