{ "openapi": "3.1.0", "info": { "title": "SocialCrawl API: Telegram", "version": "1.0.0", "description": "Unified social media data API - one API key, one consistent response format, 69 platforms, 679 endpoints. Power AI agents with clean social data.\n\nThis document covers the Telegram endpoints only (4 operations). The full contract for every platform is at https://www.socialcrawl.dev/v1/openapi.json, and every per-platform document is listed at https://www.socialcrawl.dev/openapi/index.json.", "contact": { "name": "SocialCrawl", "url": "https://www.socialcrawl.dev", "email": "socialcrawl@ridio.io" } }, "servers": [ { "url": "https://www.socialcrawl.dev/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key authentication. Send your key in the `x-api-key` request header on every call. Create and manage keys in the dashboard." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The same API key sent as `Authorization: Bearer `, the default in most agents and HTTP tools. Same key, same rules; when both headers are sent, `x-api-key` wins." } }, "schemas": { "ErrorEnvelope": { "type": "object", "description": "Unified error response envelope. Every 4xx/5xx response returns this shape; `error.type` is a machine-readable code from the API's error catalog.", "properties": { "success": { "type": "boolean", "enum": [ false ], "example": false, "description": "Always false on an error response." }, "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MISSING_API_KEY", "INVALID_API_KEY", "INSUFFICIENT_CREDITS", "INVALID_REQUEST", "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "CONCURRENCY_LIMIT", "UPSTREAM_ERROR", "SERVICE_UNAVAILABLE", "INTERNAL_ERROR", "METHOD_NOT_ALLOWED", "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "COHORT_RESULT_TOO_LARGE", "PAYLOAD_TOO_LARGE", "RATE_LIMITED", "KEY_BUDGET_EXCEEDED", "RUN_NOT_FOUND", "RUN_STATE_CONFLICT", "RUN_EXPIRED", "NEEDS_ASYNC", "CURSOR_EXPIRED", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND", "STREAM_STATE_CONFLICT" ], "example": "INVALID_REQUEST", "description": "Machine-readable error code. The per-status `x-error-codes` list on each response narrows which codes that status can carry." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "status": { "type": "integer", "description": "HTTP status code, echoed in the body." }, "doc_url": { "type": "string", "description": "Link to the docs page for this error code." }, "retryable": { "type": "boolean", "description": "Whether retrying the identical request can succeed. True for rate limits, concurrency limits, idempotency contention and transient upstream or server failures; false for every other code, including both 402s." }, "details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional structured context. Omitted on ordinary errors. Both 402s carry `reason` (`balance_too_low` or `key_budget_reached`), `retry_will_succeed: false`, a one-sentence `next_step`, and `top_up_url` or `key_settings_url`; the GET endpoints add `credits_required`; a metered endpoint adds `pricing` (`\"ceiling\"` when the hold is the most the call can cost and the unused part is refunded, `\"exact\"` when the call is charged what it holds; measured on recent production calls), `credits_typical` (on a ceiling, what a call like this is usually charged), and, when a cheaper shape of the same request exists, `lower_cost_with`, `lower_cost_options` (`param`, `value` or null to leave it out, and `credits_required` with that change) and `credits_required_cheapest`. A `max_credits` page that switched to a cheaper form to fit (`threads/search` with `expand=false`) and still found the balance short adds `balance_fallback`: the `param` and `value` it switched to, and `credits_required` for the call as sent. A page-cap rejection carries `reason: \"page_limit\"` with `max_page`, `requested_page` and `narrow_with`. An `INVALID_REQUEST` that sends no member of a required one-of group carries `fields` (the parameters of that group) and a one-sentence `next_step`. Other endpoints use it for their own taxonomies, such as the comment-lookup not-found reasons." }, "status_url": { "type": "string", "format": "uri", "description": "Present on 5xx responses: the public status page, filtered to the platform when one is known." }, "incident": { "type": "object", "description": "Present on a 5xx response when an open public incident explains the failure.", "properties": { "id": { "type": "string", "example": "k3v9w2m8q1zt" }, "title": { "type": "string" }, "status": { "type": "string", "example": "investigating" }, "impact": { "type": "string", "example": "major" }, "url": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "status", "impact", "url" ] } }, "required": [ "type", "message", "status", "doc_url" ] }, "credits_used": { "type": "integer", "description": "Net credits charged for this request. Error paths deduct-then-refund, so this is 0 in almost every case; a partial-coverage composite may keep the succeeded-leg cost." }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Credits left after this request when established. Some unauthenticated errors use null; on a prebilling route whose attempted balance lookup fails, this field is omitted instead of fabricated." }, "request_id": { "type": "string", "description": "Unique request identifier - matches the X-Request-Id header. Quote it in support requests." } }, "required": [ "success", "error", "credits_used", "request_id" ] }, "MonitorAlertRule": { "description": "A numeric condition evaluated against a monitor run and, for change operators, a previous comparable run.", "properties": { "metric": { "description": "Dot path to a numeric key in the recipe's own result, for example `coverage` or `summary.total`. On a numbers-only monitor (created with `track`) the metric must be one of `track.metrics`, and an `items[].` metric is evaluated once per row: a fired alert then carries `row_id`. The special metric `rows_new` (numbers-only monitors only; it needs an `items[].` metric in `track.metrics` and is not itself tracked) counts the list rows this run has that the previous run did not: `{\"metric\":\"rows_new\",\"op\":\"gt\",\"value\":0}` alerts on any new post or video. It accepts only `gt` and `gte`, and is skipped on the first run. \"New\" means absent from the previous successful run's stored rows (capped at `max_rows`, default 100), so a row that drops off and returns later counts as new again. An empty-page run is refunded and is not a baseline, so on a sparse feed the first run that holds rows has no baseline and stays silent: the first new post after a quiet period may not alert. Use a daily cadence or leave `max_rows` headroom.", "type": "string" }, "op": { "enum": [ "gt", "lt", "gte", "lte", "abs_change_gt", "pct_change_gt", "pct_change_lt" ], "type": "string" }, "value": { "type": "number" }, "window": { "description": "Accepted and stored, but ignored: a change op always compares against the immediately preceding comparable run, whatever the value.", "enum": [ "1d", "1w" ], "type": "string" } }, "required": [ "metric", "op", "value" ], "type": "object" }, "EventEnvelope": { "description": "One event, identical in the feed and in every webhook batch. `id` is stable for one fact, so deduplicate on it.", "properties": { "id": { "description": "Deterministic event id: the same fact never mints a second event.", "example": "evt_k3m7q2xwcbvd4nph6trz5ycgda", "type": "string" }, "type": { "description": "Dot-delimited lower-case type. Types written today: `discover.progress`, `discover.accounts_ready`, `discover.completed`, `discover.partial`, `discover.paused`, `discover.failed`, `discover.new_rows`, `discover.new_accounts`, `discover.new_items`, `discover.run_skipped`, `discover.run_failed`, `endpoint.disabled`, `mention.created`, `mention.deleted`, `stream.baseline.established`, `stream.coverage_gap`, `stream.paused`, `stream.resumed`, `stream.deleted`, `stream.budget.warning`, `stream.health`.", "example": "discover.completed", "type": "string" }, "api_version": { "example": "2026-10-01", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "cursor": { "description": "The feed position right after this event. Send it as `cursor` to read what came after; an event id works too.", "example": "c_MS4xMi4xNzkyNDA0OTA0", "type": "string" }, "subject": { "description": "The object the event is about, for example `{ kind: \"discover_run\", id: \"run_…\" }`.", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "type": [ "object", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ], "type": [ "object", "null" ] }, "data": { "description": "The event's facts. Discover events carry counts and ids, never keywords or row text.", "type": "object" }, "links": { "additionalProperties": { "type": "string" }, "description": "Absolute URLs to the subject, such as `run` and `results` (for example `https://www.socialcrawl.dev/v1/prism/discover/runs/run_...`), the same in the feed and in webhook batches. Events served before 26/10/2026 carried relative paths.", "type": "object" } }, "required": [ "id", "type", "api_version", "created_at", "cursor", "subject", "data", "links" ], "type": "object" }, "WebhookEndpoint": { "description": "A registered receiver. The signing secret is never part of it: it is returned once, by create and by rotate-secret.", "properties": { "id": { "example": "we_V1StGXR8Z5jdHi6BmyT", "type": "string" }, "url": { "example": "https://example.com/hooks/socialcrawl", "type": "string" }, "description": { "type": [ "string", "null" ] }, "types": { "description": "Subscribed event types: exact types, `ns.*` wildcards, or `*` for every type.", "items": { "type": "string" }, "type": "array" }, "subject_ids": { "description": "Only events about these subjects (a run or schedule id); null for every subject.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "enum": [ "enabled", "disabled" ], "type": "string" }, "disabled_reason": { "description": "`gone` (the receiver answered 410), `failing` (5 consecutive days of failed deliveries), `key_revoked` (the creating key was revoked or deleted) or `user` (set with PATCH). Null while enabled.", "enum": [ "gone", "failing", "key_revoked", "user", null ], "type": [ "string", "null" ] }, "failing_since": { "description": "Start of the current run of failed deliveries; null while healthy.", "format": "date-time", "type": [ "string", "null" ] }, "api_version": { "example": "2026-10-01", "type": "string" }, "secret_rotation": { "description": "Set during a rotation: until `previous_secret_expires_at` every delivery is signed with both secrets.", "properties": { "previous_secret_expires_at": { "format": "date-time", "type": "string" } }, "type": [ "object", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "next": { "description": "Ready relative URLs for the next calls.", "properties": { "attempts_url": { "type": "string" }, "events_url": { "type": "string" }, "rotate_secret_url": { "type": "string" }, "self_url": { "type": "string" }, "test_url": { "type": "string" } }, "type": "object" } }, "required": [ "id", "url", "types", "status", "api_version", "created_at" ], "type": "object" }, "WebhookAttempt": { "description": "One delivery attempt. `response_excerpt` is at most 1 KB of your receiver's answer.", "properties": { "id": { "type": "string" }, "delivery_id": { "description": "The batch's `webhook-id`, the same on every retry.", "type": "string" }, "test": { "type": "boolean" }, "status": { "description": "Your receiver's HTTP status; null for a timeout, a refused host, a network error or a secret that could not be opened.", "type": [ "integer", "null" ] }, "outcome": { "enum": [ "delivered", "failed", "gone", "retry_after", "timeout", "redirect", "refused_host", "secret_unavailable", "network_error" ], "type": "string" }, "duration_ms": { "type": [ "integer", "null" ] }, "response_excerpt": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "delivery_id", "test", "status", "outcome", "created_at" ], "type": "object" }, "EventBatch": { "description": "What every delivery carries, also for one event: at most 100 events or 256 KB. Each inner event keeps its own `id` and `cursor`; deduplicate on the inner ids. A test send marks its event `\"test\": true` with `\"cursor\": null`.", "properties": { "id": { "example": "bat_V1StGXR8Z5jdHi6BmyT", "type": "string" }, "type": { "const": "event.batch", "type": "string" }, "data": { "properties": { "events": { "items": { "$ref": "#/components/schemas/EventEnvelope" }, "maxItems": 100, "type": "array" } }, "required": [ "events" ], "type": "object" } }, "required": [ "id", "type", "data" ], "type": "object" }, "ListeningRuleAst": { "description": "A rule as a tree of `and`, `or`, `not`, `term`, `phrase` and `field` nodes, as the dry run returns it in `data.stream.groups[].ast`.", "anyOf": [ { "type": "object", "properties": { "and": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ListeningRuleAst" } } }, "required": [ "and" ], "additionalProperties": false }, { "type": "object", "properties": { "or": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ListeningRuleAst" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/ListeningRuleAst" } }, "required": [ "not" ], "additionalProperties": false }, { "type": "object", "properties": { "term": { "type": "string", "minLength": 1 } }, "required": [ "term" ], "additionalProperties": false }, { "type": "object", "properties": { "phrase": { "type": "string", "minLength": 1 } }, "required": [ "phrase" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "lang", "country", "platform", "site", "community" ] }, "value": { "type": "string", "minLength": 1 } }, "required": [ "field", "value" ], "additionalProperties": false } ] } } }, "tags": [ { "name": "telegram", "description": "Telegram endpoints" } ], "paths": { "/telegram/profile": { "get": { "summary": "Get Telegram channel profile", "description": "Returns a public Telegram channel or group profile including its display name, description, avatar URL, verification status, and subscriber count. The subscriber count is exact rather than abbreviated. Private channels, invite-only groups, and channels with no public preview return 404.", "tags": [ "telegram" ], "operationId": "get_telegram_profile", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Telegram handle, with or without the leading @, or a t.me channel URL", "schema": { "type": "string" }, "example": "telegram" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 900 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "telegram" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/telegram/profile" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "author": { "type": "object", "description": "Canonical Author object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "number", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "number", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "enum": [ "app", "web", null ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "number", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "object", "null" ], "description": "Object at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "number", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", null ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "author" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/profile", "data": { "author": { "id": "6917704832925746181", "username": "duolingo", "display_name": "Duolingo", "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/6b2beff1167b40574fcd2ea2caf1444d~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=f3757781&x-expires=1784674800&x-signature=9OCuBINSoeHVQPclR1XuqeA1j%2FE%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5", "bio": "hot owl summer 🔥🦉", "verified": true, "followers": 17100000, "following": 310, "posts_count": 1129, "likes_count": 482200000, "url": null, "private": false, "joined_at": null }, "computed": { "engagement_rate": null, "language": null, "content_category": "other", "estimated_reach": null }, "_warnings": [ "computed.engagement_rate: author ratio exceeded 1.0 (raw: 28.19883); returned null — a lifetime likes/followers ratio is not a real engagement rate" ] }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/telegram/profile/posts": { "get": { "summary": "List Telegram channel posts", "description": "Returns one page of recent public posts from a Telegram channel or group, newest page first. Each post carries its text, publish time, view count, the per-emoji reaction breakdown, and direct media URLs for photos and videos. Pass the returned cursor to walk further back through the channel's history. Page size varies because photo albums count as one post and service messages are skipped, so a short page does not mean the end of the channel: keep paging until the cursor is absent. Send `q` to search inside the channel instead: you get one page of the newest messages that contain every word of `q` (up to about 20), at the same price, with no cursor.", "tags": [ "telegram" ], "operationId": "get_telegram_profile_posts", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "handle", "in": "query", "required": true, "description": "Public Telegram handle, with or without the leading @, or a t.me channel URL", "schema": { "type": "string" }, "example": "telegram" }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor from the previous page's pagination block. Omit it for the most recent posts.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Words to search for inside the channel, for example `cheap watches`. Returns one page of the newest messages whose text contains every word (put a phrase in double quotes to require it as written), at the same price as a plain page. Telegram's own search also matches other forms of a word (`watch` for `watches`); those messages are left out, because they do not contain the words. A search page has no cursor, so `q` cannot be combined with `cursor`.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.", "schema": { "type": "string" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "telegram" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/telegram/profile/posts" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical post wrappers ({ post, computed })", "items": { "type": "object", "description": "Canonical post wrapper", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "number", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "number", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "number", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "number", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "number", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "number", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked; discover reads a country from it into `geo.country` (`source: author_location`). Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "number", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "enum": [ "video", "short", "live", "channel", "playlist", null ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "number", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "number", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", null ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "number", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "number", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "number", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "number", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "number", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "object", "null" ], "description": "Object at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "object", "null" ], "description": "Object at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "number", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "object", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "object", "null" ], "description": "Object at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "object", "description": "Object at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "number", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "enum": [ "minute", "hour", "day", "week", "month", "year", null ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "object", "null" ], "description": "Object at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String at post.ext.dsp_ids.*" } }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "object", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "object", "null" ], "description": "Object at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "number", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "number", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "telegram", "endpoint": "/v1/telegram/profile/posts", "data": { "items": [ { "post": { "id": "441", "url": "https://t.me/telegram/441", "content": { "text": "Bot-to-Bot Communication. Bots are now able to respond to other bots, not just users. AI enthusiasts can utilize this to create custom workflows with autonomous agents. May Features 1 • 2 • 3 • 4 • 5 • More", "media_urls": [ "https://cdn1.telesco.pe/file/c01503a63e.mp4?token=F1gyI_bSWGGmbhhTHD0hMW_MtU4-kbyesJeEJn3igVvTkXoBNkzhVz4sQNFp1jDHFmXnCCA3EZI5bGQ4QmxgfRef2vsj_SlJBV5NLH_cNSFZZ7c0qGtZ1p_HZZg9-zyq1oc42IFQJU0mqEoikbw1CkYYcKz1mEUCMDNNlS8ZAXrmGLI2Fdhxz3GL52gMgW1tK-AMpbA9x9gGTGICfMvtV-F8AVQ15qODzIBYK7CnoDgcXeYtML9zpg4XCMTj986PEfdu9YJgKkwSIX2-qhdqNZ1f3JJ1jEFOjYSjemyguBA2uLcizrhgPx_QUS_MjSt0fozZh7UCF5iHuR-Nt9-t8w" ], "thumbnail_url": "https://cdn1.telesco.pe/file/TZVrsEkjo46ptIfD67o-2JlmqjBFjV8b0e84pGqKspohb_QAe-8eoQcPRzbfUbZauMYNqgJPm8P-S0hNaahM1u_5QEgK5k6GRVwNxfV3NihTEbNKK6r3Ge1MkFJkhyQf2HzVN9svBi39Qq2KFm41_ww4ITTv-Wd5DQqkYqTxOQb5j_YbzMlf5K7TlHBhbrnqhjKUK9XX1tac9f4LwjwC-UonFh6F27LJ718u7-PVV4O_82W4k5AEw1oUpOWW6KvrduB3pKgydwsrY9GGRUQimXMoW5QgtpfohngHQVtHXNqA2pKeMWTyKIVOcGKEPKx-0Ikb3XHmkwvVY92c9vFV7g", "duration_seconds": 6 }, "author": { "username": "telegram", "display_name": "user_41eca1", "avatar_url": null, "verified": null }, "engagement": { "views": 1510000, "likes": 0, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-05-14T16:08:31.000Z", "ext": { "reaction_counts": [] } }, "computed": { "engagement_rate": 0, "language": "en", "content_category": "other", "estimated_reach": 1812000 } }, { "post": { "id": "442", "url": "https://t.me/telegram/442", "content": { "text": "Chat Automation in Profiles. Every Telegram user can now connect a bot to their profile – and let it respond to messages on their behalf. May Features 1 • 2 • 3 • 4 • 5 • More", "media_urls": [ "https://cdn1.telesco.pe/file/eb82a15bbc.mp4?token=TCgYjeeMZ8_BQes9nz1KGIc8voR2n6Lh7l82AVBjuiUI39RBC4sdSV8WASZbwiYUpQhjVUBUoF3Dra_cKLVBAUMQimR9bDswMpo1hJQUSmlLwOCu7RE_pWdDJ28L5PKSQbRke9dsBhFbUcc6zTuXu8CZmJrQ81pkU8mhZKkRxZxDt5-_4EbgrpvR36YLeC-yfDxiXmXhtROxOIQUUWlxCZdOtO3QJVIPfWSKwLjxZ69CBAOqfV1KcGujApFCEV2e_dMINn8SN-gWWI9pMD9rxwPB54NGq0IKn5ZeXWCFbsxxwnmUADypQih7RlUsyCg8gl6YTl4r9Q41hHB6ixHnaQ" ], "thumbnail_url": "https://cdn1.telesco.pe/file/ParfGSJ07OpSSu3uYtVKx4IWRYq561PeQDj1O-r0WJ-YMq9DlL-ogwnI5NiMQ89DLsJeiCTtN1QdXpXoq4y6HTDU4gwcvl3J1tnQY8N8TWgX7keiIQDTbavkTUdgV_bBjkCUO0bcfEe_uCdpAp0SQ3PyaGH4xXgl0GR_L6KIhH3IjMFef6ix23BPFjCRprLpNp1JTnNak3dvMiRaRwB3lIpOEJ791Iz4secg-NgK4v8-kM88ugKLJXF2H9YNtB3oBUu3u4J1YxDTeMyw61sA_ZjqUa-TqfBzQ28aBY4k1fp6DXqnH8SZGOjTOrOwbUI9aV_l4jdE2WgUXg-QMBzCBA", "duration_seconds": 9 }, "author": { "username": "telegram", "display_name": "user_41eca1", "avatar_url": null, "verified": null }, "engagement": { "views": 1320000, "likes": 0, "comments": null, "shares": null, "saves": null }, "flags": { "nsfw": null, "spoiler": null, "pinned": null, "deleted": false }, "published_at": "2026-05-14T16:08:52.000Z", "ext": { "reaction_counts": [] } }, "computed": { "engagement_rate": 0, "language": "en", "content_category": "other", "estimated_reach": 1584000 } } ], "next_cursor": "441", "total": null, "dropped": 0 }, "credits_used": 1, "request_id": "req_example000000", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiNDQxIiwiZSI6InRlbGVncmFtL3Byb2ZpbGUvcG9zdHMiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 20 }, "credits_remaining": 9999 } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/telegram/post": { "get": { "summary": "Get Telegram post", "description": "Returns one public Telegram post by its t.me URL, including the text, publish time, view count, the per-emoji reaction breakdown, and direct media URLs. View and reaction counts on posts are rounded by Telegram's own public preview, so use them for ranking rather than for exact deltas.", "tags": [ "telegram" ], "operationId": "get_telegram_post", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 1, "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public Telegram post URL, in the form https://t.me/{handle}/{id}", "schema": { "type": "string" }, "example": "https://t.me/durov/546" }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 600 seconds old is served; this endpoint keeps copies for 3600 seconds, so a value up to 3600 can save a call. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 3600 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "telegram" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/telegram/post" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "post": { "type": "object", "description": "Canonical Post object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific post ID (always a string; numeric upstream IDs are stringified)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the post on the source platform" }, "content": { "type": "object", "description": "Post content fields (text, media, thumbnail, duration)", "properties": { "text": { "type": [ "string", "null" ], "description": "Post caption, description, or text content" }, "media_urls": { "type": [ "string", "array", "null" ], "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.", "items": { "type": "string", "description": "URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels." } }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL to thumbnail image" }, "duration_seconds": { "type": [ "number", "null" ], "description": "Video/clip duration in seconds (null for non-video posts)" } } }, "author": { "type": "object", "description": "Subset of Author fields for the post creator", "properties": { "username": { "type": [ "string", "null" ], "description": "Author username" }, "display_name": { "type": [ "string", "null" ], "description": "Author display name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to author profile picture" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the author account is verified" } } }, "engagement": { "type": "object", "description": "Engagement counts", "properties": { "views": { "type": [ "number", "null" ], "description": "View count (if available). For Instagram video/reels this is the play count: the headline 'Views' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram's play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`." }, "likes": { "type": [ "number", "null" ], "description": "Like / reaction count" }, "comments": { "type": [ "number", "null" ], "description": "Comment count. Note: on `GET /v1/instagram/post` this is Instagram's `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field." }, "shares": { "type": [ "number", "null" ], "description": "Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated)." }, "saves": { "type": [ "number", "null" ], "description": "Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated)." } } }, "flags": { "type": "object", "description": "Boolean flags on the post", "properties": { "nsfw": { "type": [ "boolean", "null" ], "description": "NSFW flag (null when platform does not surface)" }, "spoiler": { "type": [ "boolean", "null" ], "description": "Spoiler flag (null when platform does not surface)" }, "pinned": { "type": [ "boolean", "null" ], "description": "Pinned-to-profile flag (null when platform does not surface)" }, "deleted": { "type": "boolean", "description": "Whether the post is tombstoned (always present)" }, "likes_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts." }, "comments_hidden": { "type": [ "boolean", "null" ], "description": "Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts." }, "shares_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.shares_hidden" }, "views_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.views_hidden" }, "saves_hidden": { "type": [ "boolean", "null" ], "description": "Boolean at post.flags.saves_hidden" } } }, "published_at": { "type": [ "string", "number", "null" ], "description": "Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle." }, "ext": { "type": [ "object", "null" ], "description": "Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)", "properties": { "music_id": { "type": [ "string", "null" ], "description": "TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound" }, "matched_song_id": { "type": [ "string", "null" ], "description": "TikTok only. The catalogue song TikTok matched the video's sound to, as an exact digit string. An official clip and the original sounds creators upload with it have different `music_id` values and the same `matched_song_id`, so group rows on it to count every use of one song. It is not a clipId: `/v1/tiktok/song` and `/v1/tiktok/song/videos` do not accept it. `/v1/tiktok/search/music` carries it on each sound, so a search on the song's title and artist, kept to the sounds with the same `matched_song_id`, gives the song's official sounds and their `video_count`. Absent when TikTok matched the sound to no song, and on rows served from a source that does not report the match." }, "matched_song_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the song in `matched_song_id`. Absent when there is no matched song." }, "matched_song_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist of the song in `matched_song_id`, as TikTok's catalogue names it. Absent when there is no matched song." }, "music_title": { "type": [ "string", "null" ], "description": "TikTok only. The title of the video's own sound (`music_id`). An uploaded sound is titled like `original sound - `; the song it plays, when TikTok recognised one, is `matched_song_title`." }, "music_artist": { "type": [ "string", "null" ], "description": "TikTok only. The artist TikTok shows for the video's own sound. On an original sound this is the uploader's display name, not the song's artist; use `matched_song_artist` for that." }, "music_is_original": { "type": [ "boolean", "null" ], "description": "TikTok only. `true` when the video's sound is an original sound a creator uploaded, `false` when it is a catalogue track. Absent when the source does not say." }, "author_id": { "type": [ "string", "null" ], "description": "The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `/v1/instagram/search/reels`, `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` items it is present on every row, accepted by `/v1/instagram/profile/country?user_id=` and `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle." }, "author_url": { "type": [ "string", "null" ], "description": "The posting account's profile URL, so a matching post can be followed to its account. Present on `/v1/facebook/search/posts` rows: the vanity or `/people///` URL when Facebook sends one, otherwise `https://www.facebook.com/profile.php?id=` built from the account id. Pass it as `url` to `/v1/facebook/profile` (or to `/v1/prism/profiles` with `platform: facebook`). Null when the row names neither an account URL nor a numeric account id. Absent on other endpoints." }, "author_followers": { "type": [ "number", "null" ], "description": "The creator's follower count as embedded in the search payload itself, when the search source happens to carry one. On Instagram `search/reels` it is null on a plain call, because Instagram stopped sending follower counts in its search payload in August 2026; send `include=creator` (or `country`) and it is filled from the creator's profile, 2 credits per creator looked up. It stays null when that lookup does not resolve." }, "author_following": { "type": [ "number", "null" ], "description": "Numeric at post.ext.author_following" }, "author_posts_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.author_posts_count" }, "author_location": { "type": [ "string", "null" ], "description": "The free text the author wrote in their profile's location field, exactly as written (for example `Johannesburg, South Africa`). It is not a country code and is not checked; discover reads a country from it into `geo.country` (`source: author_location`). Present on X tweet and reply rows; null or absent when the author left it blank." }, "in_reply_to_id": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_id" }, "in_reply_to_username": { "type": [ "string", "null" ], "description": "String at post.ext.in_reply_to_username" }, "conversation_id": { "type": [ "string", "null" ], "description": "String at post.ext.conversation_id" }, "author_country": { "type": [ "string", "null" ], "description": "The creator's country. On Instagram it is the country the creator declares on the About this account panel, as a country name (for example `Spain`), and it is not where the post was filmed. It is present on `/v1/instagram/search/reels` when the request sends `include=creator`, `include=country` or `country`, and on `/v1/instagram/search/hashtag` and `/v1/instagram/location/posts` when it sends `include=country`, filled by looking the creator up. On YouTube rows joined with `include=channel` it is the channel's own country as an ISO 3166-1 alpha-2 code (for example `ZA`). Null when the platform publishes no country for the creator or the lookup did not resolve, and nothing is guessed; absent on a plain call." }, "author_public_email": { "type": [ "string", "null" ], "description": "The public contact email on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public email or the lookup did not resolve; absent on a plain call." }, "author_public_phone": { "type": [ "string", "null" ], "description": "The public contact phone number on the creator's profile. Present only on `/v1/instagram/search/reels` when the request sends `include=creator`, filled by looking the creator up. Null when the creator lists no public phone or the lookup did not resolve; absent on a plain call." }, "download_count": { "type": [ "number", "null" ], "description": "How many times the video has been saved to a device. TikTok only, and distinct from `engagement.saves`: a save keeps the video in a private collection on the platform, a download takes a copy off it, and TikTok counts the two separately. Present on TikTok post, search and post-list responses; absent everywhere else." }, "region": { "type": [ "string", "null" ], "description": "TikTok only: the country TikTok registers the video to, as an ISO 3166-1 alpha-2 code (normally the creator's account country when they posted). It is not the viewer's country, not the `region` you requested, and not a language. On `/v1/tiktok/trending`, `/v1/tiktok/search`, `/v1/tiktok/search/top`, `/v1/tiktok/profile/videos`, `/v1/tiktok/search/hashtag` and `/v1/tiktok/song/videos` it is how you tell which rows are from a given country: filter on it when you need only that country. A row whose source omits the country stays null. The `region` request parameter still only sets the proxy." }, "subreddit": { "type": [ "string", "null" ], "description": "Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`" }, "title": { "type": [ "string", "null" ], "description": "String at post.ext.title" }, "selftext": { "type": [ "string", "null" ], "description": "String at post.ext.selftext" }, "link_domain": { "type": [ "string", "null" ], "description": "String at post.ext.link_domain" }, "upvote_ratio": { "type": [ "number", "null" ], "description": "Reddit only: the share of a post's votes that are upvotes, as a fraction from 0 to 1 and usually close to 1 (six live rows measured 1, 1, 1, 0.86, 0.75, 1). Fractional despite the integer type this schema emits for every numeric leaf, the same caveat as `author.ext.average_rating`. Populated on `/v1/reddit/search` rows whose source carries it, and null everywhere else on Reddit including `/v1/reddit/post` and `/v1/reddit/subreddit`." }, "flair": { "type": [ "string", "null" ], "description": "String at post.ext.flair" }, "content_language": { "type": [ "string", "null" ], "description": "The language the platform itself tags the post with, when it sends one: Reddit's own language tag on Reddit lanes, and TikTok's caption-language tag (for example `de`) on `/v1/tiktok/trending?feed=local`. Null when the platform could not tell (Reddit `und`, TikTok `un`, common on short or emoji-only captions); absent where the source sends no tag. Never inferred from the text by us: that is `post.computed.language`." }, "type": { "type": [ "string", "null" ], "description": "String at post.ext.type" }, "content_type": { "type": [ "string", "null" ], "enum": [ "video", "short", "live", "channel", "playlist", null ], "description": "Leaf at post.ext.content_type" }, "ticker_symbols": { "type": [ "array", "null" ], "description": "Array at post.ext.ticker_symbols", "items": { "type": "string", "description": "String at post.ext.ticker_symbols" } }, "video_view_count": { "type": [ "number", "null" ], "description": "Instagram's legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead." }, "ig_play_count": { "type": [ "number", "null" ], "description": "Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts." }, "repost_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.repost_count" }, "media_type": { "type": [ "string", "null" ], "enum": [ "image", "video", "carousel", null ], "description": "Leaf at post.ext.media_type" }, "text_truncated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.text_truncated" }, "ip_location": { "type": [ "string", "null" ], "description": "String at post.ext.ip_location" }, "carousel_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.carousel_count" }, "remix_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.remix_count" }, "audio_cluster_id": { "type": [ "string", "null" ], "description": "Instagram's audio cluster for a reel, as an exact digit string: the id Instagram uses to group different uploads of the same sound. Present on `/v1/instagram/audio/reels` rows and on `/v1/instagram/profile/reels` with `include=stats`; absent on a row when it is not available and on every other surface." }, "facebook_likes": { "type": [ "number", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.likes` on this row. A post shared to Facebook arrives from some sources with its Facebook likes already folded into the Instagram count, so the share is subtracted and published here, which keeps `engagement.likes` the Instagram-only figure instagram.com shows on the post. Add the two together for the combined number. Absent when the read carried no Facebook share, and absent on a post whose owner hides the like count, because nothing can be subtracted from a null. A response that excluded a share also carries a note in `data._warnings`." }, "facebook_comments": { "type": [ "number", "null" ], "description": "Instagram only: the Facebook cross-post share that was EXCLUDED from `engagement.comments` on this row, the comment counterpart of `post.ext.facebook_likes`. Each leaf appears only for the count it actually changed, so a post whose likes are hidden but whose comments were reconciled carries this one alone." }, "instagram_views": { "type": [ "number", "null" ], "description": "Instagram only: the Instagram-only play count of a video, the same figure on every Instagram endpoint. `engagement.views` keeps each endpoint's established meaning: on `/v1/instagram/profile/reels`, `/v1/instagram/audio/reels`, `/v1/instagram/search/reels` and `/v1/instagram/search/hashtag` it can include the post's Facebook cross-post views, while on `/v1/instagram/post` and `/v1/instagram/post/stats` it is Instagram-only. Read this leaf when you compare one post across endpoints. Absent on photos and when the source did not report the Instagram-only figure." }, "facebook_views": { "type": [ "number", "null" ], "description": "Instagram only: the Facebook cross-post part of a video's play count, the counterpart of `post.ext.instagram_views`. Present only when the source reported the Facebook part, or a combined total above the Instagram figure. Absent does not mean zero: some sources report the Instagram figure alone even for a cross-posted video." }, "published_at_epoch": { "type": [ "number", "null" ], "description": "Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form." }, "usertags": { "type": [ "array", "null" ], "description": "Array at post.ext.usertags", "items": { "description": "Leaf at post.ext.usertags" } }, "coauthors": { "type": [ "array", "null" ], "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).", "items": { "description": "Instagram collaborative posts (the native \"Collab\" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post)." } }, "music": { "type": [ "object", "null" ], "description": "Object at post.ext.music" }, "sponsor_tags": { "type": [ "array", "null" ], "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint.", "items": { "description": "Instagram only: the brand accounts the post tags as its paid partner, as usernames (`[\"rolex\"]`). `[]` on a post with no partner tagged. Present on `/v1/instagram/post/stats`; absent on every other endpoint." } }, "sponsored_disclosed": { "type": [ "boolean", "null" ], "description": "The platform's own disclosure that the post is paid or promotional: on Instagram the paid-partnership label (`is_paid_partnership`) or a tagged brand partner, on TikTok the label TikTok shows viewers (\"Paid partnership\", \"Commission paid\", \"Promotional content\"). `false` when the post carries the flag unset, null when it carries none. Present on `/v1/instagram/post/stats`, `/v1/instagram/profile/posts`, `/v1/instagram/profile/reels`, `/v1/instagram/search/reels`, `/v1/tiktok/profile/videos` and `/v1/tiktok/search`; absent on every other endpoint." }, "ai_label": { "type": [ "string", "null" ], "description": "Instagram only: Instagram's AI-content label on the post, as the method Instagram reports: `classifier_score_high` (Instagram detected it, shown as \"Likely made with AI\"), `ai_created` or `ai_edited` (declared or detected as made or edited with AI). Null when the post carries no AI label. Present on `/v1/instagram/post/stats`; absent on every other endpoint." }, "story_mentions": { "type": [ "array", "null" ], "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the accounts the story mentions with a mention sticker, as usernames in alphabetical order. `[]` when it mentions nobody. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "story_links": { "type": [ "array", "null" ], "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: where the story's link stickers lead, as URLs in alphabetical order. Instagram wraps each link in its own redirect with a per-view click id; both are removed, so this is the destination itself. `[]` when the story has no link sticker. Present on `/v1/instagram/stories` and `/v1/instagram/highlight/detail`; absent on every other endpoint." } }, "story_reshared_posts": { "type": [ "array", "null" ], "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint.", "items": { "type": "string", "description": "Instagram stories only: the feed posts the story reshares, as post URLs (`https://www.instagram.com/p/{shortcode}/`, which `/v1/instagram/post` takes). `[]` when it reshares none. Present on `/v1/instagram/stories`; absent on every other endpoint." } }, "location": { "type": [ "object", "null" ], "description": "Object at post.ext.location" }, "media": { "type": [ "array", "null" ], "description": "Array at post.ext.media", "items": { "type": "object", "description": "Nested object: post.ext.media", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "description": "Leaf at post.ext.media.type" }, "url": { "type": [ "string", "null" ], "description": "String at post.ext.media.url" }, "width": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.width" }, "height": { "type": [ "number", "null" ], "description": "Numeric at post.ext.media.height" } } } }, "top_comments": { "type": [ "array", "null" ], "description": "Array at post.ext.top_comments", "items": { "type": "object", "description": "Nested object: post.ext.top_comments", "properties": { "id": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.id" }, "text": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.text" }, "username": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.username" }, "likes": { "type": [ "number", "null" ], "description": "Numeric at post.ext.top_comments.likes" }, "published_at": { "type": [ "string", "null" ], "description": "String at post.ext.top_comments.published_at" } } } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at post.ext.hashtags", "items": { "type": "string", "description": "String at post.ext.hashtags" } }, "mentions": { "type": [ "array", "null" ], "description": "Array at post.ext.mentions", "items": { "type": "string", "description": "String at post.ext.mentions" } }, "mentioned_user_ids": { "type": [ "array", "null" ], "description": "Array at post.ext.mentioned_user_ids", "items": { "type": "string", "description": "String at post.ext.mentioned_user_ids" } }, "quoted_post": { "type": [ "object", "null" ], "description": "Threads quote posts: the post this one quotes, as `{ id, url, author: { id, username }, text, media_urls, thumbnail_url }`. A quote post usually carries no caption or media of its own, and the text and video you see on the post's page belong to this attachment, by a different author. It is returned here rather than merged into `post.content`, so `content.*` always stays the outer post's own content and one account's media is never attributed to another. Absent on posts that are not quote posts." }, "retweeted_post": { "type": [ "object", "null" ], "description": "Object at post.ext.retweeted_post" }, "quote_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.quote_count" }, "all_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.all_media_urls", "items": { "type": "string", "description": "String at post.ext.all_media_urls" } }, "reaction_counts": { "type": [ "array", "null" ], "description": "Array at post.ext.reaction_counts", "items": { "description": "Leaf at post.ext.reaction_counts" } }, "share_urn": { "type": [ "string", "null" ], "description": "String at post.ext.share_urn" }, "post_type": { "type": [ "string", "null" ], "description": "String at post.ext.post_type" }, "activity_id": { "type": [ "string", "null" ], "description": "String at post.ext.activity_id" }, "published_at_precision": { "type": [ "string", "null" ], "description": "String at post.ext.published_at_precision" }, "author_urn": { "type": [ "string", "null" ], "description": "String at post.ext.author_urn" }, "author_headline": { "type": [ "string", "null" ], "description": "String at post.ext.author_headline" }, "author_type": { "type": [ "string", "null" ], "description": "String at post.ext.author_type" }, "is_repost_quote": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.is_repost_quote" }, "article": { "type": [ "object", "null" ], "description": "Object at post.ext.article" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at post.ext.reaction_type" }, "download_media_urls": { "type": [ "array", "null" ], "description": "Array at post.ext.download_media_urls", "items": { "type": "object", "description": "Object at post.ext.download_media_urls" } }, "tags": { "type": [ "array", "null" ], "description": "Array at post.ext.tags", "items": { "type": "string", "description": "String at post.ext.tags" } }, "categoryId": { "type": [ "string", "null" ], "description": "String at post.ext.categoryId" }, "categoryTitle": { "type": [ "string", "null" ], "description": "String at post.ext.categoryTitle" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at post.ext.topicCategories", "items": { "type": "string", "description": "String at post.ext.topicCategories" } }, "duration": { "type": [ "string", "null" ], "description": "String at post.ext.duration" }, "license": { "type": [ "string", "null" ], "description": "String at post.ext.license" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.madeForKids" }, "defaultAudioLanguage": { "type": [ "string", "null" ], "description": "String at post.ext.defaultAudioLanguage" }, "hasPaidProductPlacement": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.hasPaidProductPlacement" }, "caption": { "type": [ "string", "null" ], "description": "String at post.ext.caption" }, "position": { "type": [ "number", "null" ], "description": "Numeric at post.ext.position" }, "playlistId": { "type": [ "string", "null" ], "description": "String at post.ext.playlistId" }, "videoOwnerChannelId": { "type": [ "string", "null" ], "description": "String at post.ext.videoOwnerChannelId" }, "videoPublishedAt": { "type": [ "string", "null" ], "description": "String at post.ext.videoPublishedAt" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.description" }, "default_language": { "type": [ "string", "null" ], "description": "String at post.ext.default_language" }, "localizations": { "type": [ "object", "null" ], "description": "Object at post.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: post.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at post.ext.localizations.*.description" } } } }, "playlist_item_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_item_id" }, "playlist_owner_channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_channel_id" }, "playlist_owner_title": { "type": [ "string", "null" ], "description": "String at post.ext.playlist_owner_title" }, "channel_id": { "type": [ "string", "null" ], "description": "String at post.ext.channel_id" }, "published_label": { "type": [ "string", "null" ], "description": "String at post.ext.published_label" }, "published_precision": { "type": [ "string", "null" ], "enum": [ "minute", "hour", "day", "week", "month", "year", null ], "description": "Leaf at post.ext.published_precision" }, "title_maybe_translated": { "type": [ "boolean", "null" ], "description": "Boolean at post.ext.title_maybe_translated" }, "video_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.video_count" }, "posts_count": { "type": [ "number", "null" ], "description": "`/v1/instagram/hashtag` only: the exact number of public posts Instagram counts under the hashtag. Live: it moves between calls minutes apart." }, "commerce": { "type": [ "object", "null" ], "description": "Object at post.ext.commerce" }, "on_screen_texts": { "type": [ "array", "null" ], "description": "Array at post.ext.on_screen_texts", "items": { "type": "string", "description": "String at post.ext.on_screen_texts" } }, "topic_tag": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag" }, "reshare_count": { "type": [ "number", "null" ], "description": "Numeric at post.ext.reshare_count" }, "dsp_ids": { "type": [ "object", "null" ], "description": "Object at post.ext.dsp_ids", "additionalProperties": { "type": "string", "description": "String at post.ext.dsp_ids.*" } }, "topic_tag_id": { "type": [ "string", "null" ], "description": "String at post.ext.topic_tag_id" }, "amazon_shop_lists": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_lists", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_lists" } }, "amazon_shop_trending_picks": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_trending_picks", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_trending_picks" } }, "amazon_shop_curations": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_curations", "items": { "type": "object", "description": "Object at post.ext.amazon_shop_curations" } }, "amazon_shop_socials": { "type": [ "array", "null" ], "description": "Array at post.ext.amazon_shop_socials", "items": { "type": "string", "description": "String at post.ext.amazon_shop_socials" } }, "ad": { "type": [ "object", "null" ], "description": "Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface." }, "apple_music": { "type": [ "object", "null" ], "description": "Object at post.ext.apple_music" }, "feedback_id": { "type": [ "string", "null" ], "description": "String at post.ext.feedback_id" }, "question_id": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN (`/v1/naver/kin/search`) only: the question's id (Naver's `docId`), read from the row's link. Kin returns one row per answer, so several rows can share it; send `group=question` for one row per question." }, "answer_no": { "type": [ "number", "null" ], "description": "Naver KnowledgeiN only: which answer of the question this row is (Naver's `answerNo`), read from the row's link." }, "answer_nos": { "type": [ "array", "null" ], "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first.", "items": { "type": "number", "description": "Naver KnowledgeiN with `group=question` only: every answer number of the question that was on the page, best-ranked first." } }, "published_at_est": { "type": [ "string", "null" ], "description": "Naver KnowledgeiN only: the question's date ESTIMATED from its id (`YYYY-MM-DD`, Korea time), never a published date, so `published_at` stays null. Absent for questions older than the calibration table." }, "date_basis": { "type": [ "string", "null" ], "description": "How `post.ext.published_at_est` was derived. `kin_docid_estimate`: interpolated from the question id against question pages whose posted date was read." }, "event": { "type": [ "object", "null" ], "description": "Object at post.ext.event" }, "trend": { "type": [ "object", "null" ], "description": "Trend-board envelope: what TikTok's own trend board says about the row. On `/v1/tiktok/hashtags/popular`: `rank`, `country_code`, `period_days`, `posts` and `views` for the window (not lifetime totals), `industry` / `industry_id` / `industry_label` for the first board the hashtag was read from (null for the overall board), `boards` listing EVERY board it ranks on as `{ industry, industry_id, industry_label, rank }` in board order (so a hashtag in the top 3 overall and on an industry board shows both), `popularity_curve` as `{ date, value }` with value 0 to 100 relative to the window's peak, and `top_creators`. On `/v1/tiktok/videos/popular`: `rank`, `country_code`, `period_days`, `order_by`, `period_views`, `organic_views`, `engagement_rate`, `six_second_view_through_rate`, `content_tags`. Absent on every non-board surface." }, "updated_at": { "type": [ "string", "null" ], "description": "String at post.ext.updated_at" }, "alt_text": { "type": [ "string", "null" ], "description": "String at post.ext.alt_text" }, "board_name": { "type": [ "string", "null" ], "description": "String at post.ext.board_name" }, "numeric_id": { "type": [ "number", "null" ], "description": "Numeric at post.ext.numeric_id" }, "outbound_url": { "type": [ "string", "null" ], "description": "String at post.ext.outbound_url" }, "group": { "type": [ "object", "null" ], "description": "Object at post.ext.group" } } } } }, "computed": { "type": "object", "description": "Server-computed analytics fields (consistent across platforms)", "properties": { "engagement_rate": { "type": [ "number", "null" ], "description": "Computed engagement rate (0..1). Null when the upstream lacks enough signal." }, "language": { "type": [ "string", "null" ], "description": "ISO 639-1 language code detected from the post text. Null when undetectable." }, "content_category": { "type": [ "string", "null" ], "description": "Keyword-classified content category (e.g. tech, food, gaming). Null when undetectable." }, "estimated_reach": { "type": [ "number", "null" ], "description": "Estimated reach based on views or follower count. Null when uncomputable." }, "save_rate": { "type": [ "number", "null" ], "description": "Numeric at computed.save_rate" }, "relevance": { "type": [ "object", "null" ], "description": "Nested object: computed.relevance", "properties": { "p": { "type": "number", "description": "Numeric at computed.relevance.p" }, "sense": { "type": "string", "enum": [ "target", "other_named_thing", "generic_word", "not_present" ], "description": "Leaf at computed.relevance.sense" }, "depth": { "type": "number", "description": "Numeric at computed.relevance.depth" }, "spam": { "type": "number", "description": "Numeric at computed.relevance.spam" } } }, "labels": { "type": [ "object", "null" ], "description": "Object at computed.labels", "additionalProperties": { "type": "object", "description": "Object at computed.labels.*", "additionalProperties": { "type": [ "number", "string", "boolean", "null" ], "description": "Union: number | string | boolean" } } }, "labels_evidence": { "type": [ "object", "null" ], "description": "Object at computed.labels_evidence", "additionalProperties": { "type": [ "object", "null" ], "description": "Nested object: computed.labels_evidence.*", "properties": { "quote": { "type": "string", "description": "String at computed.labels_evidence.*.quote" }, "sentence_index": { "type": "integer", "description": "Numeric at computed.labels_evidence.*.sentence_index" } } } } } }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "post" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached" ] }, "example": { "success": true, "platform": "youtube", "endpoint": "/v1/youtube/video", "data": { "post": { "id": "dQw4w9WgXcQ", "content": { "text": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", "duration_seconds": 214, "media_urls": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw" }, "author": { "username": "UCuAXFkgsw1L7xaCfnd5JJOw", "display_name": "Rick Astley", "avatar_url": null, "verified": null }, "engagement": { "views": 1789065639, "likes": 19216844, "comments": 2443809, "shares": null, "saves": null }, "published_at": "2009-10-25T06:57:33Z", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "ext": { "content_type": "video", "tags": [ "rick astley", "Never Gonna Give You Up", "nggyu", "never gonna give you up lyrics", "rick rolled", "Rick Roll", "rick astley official", "rickrolled", "Fortnite song", "Fortnite event", "Fortnite dance", "fortnite never gonna give you up", "rick roll", "rickrolling", "rick rolling", "never gonna give you up", "80s music", "rick astley new", "animated video", "rickroll", "meme songs", "never gonna give u up lyrics", "Rick Astley 2022", "never gonna let you down", "animated", "rick rolls 2022", "never gonna give you up karaoke" ], "categoryId": "10", "categoryTitle": "Music", "topicCategories": [ "https://en.wikipedia.org/wiki/Electronic_music", "https://en.wikipedia.org/wiki/Music", "https://en.wikipedia.org/wiki/Pop_music", "https://en.wikipedia.org/wiki/Rhythm_and_blues", "https://en.wikipedia.org/wiki/Soul_music" ], "duration": "PT3M34S", "license": "youtube", "madeForKids": false, "defaultAudioLanguage": "en", "hasPaidProductPlacement": false, "caption": "true", "description": "The official video for “Never Gonna Give You Up” by Rick Astley. \n\nNever: The Autobiography 📚 OUT NOW! \nFollow this link to get your copy and listen to Rick’s ‘Never’ playlist ❤️ #RickAstleyNever\nhttps://linktr.ee/rickastleynever\n\n“Never Gonna Give You Up” was a global smash on its release in July 1987, topping the charts in 25 countries including Rick’s native UK and the US Billboard Hot 100. It also won the Brit Award for Best single in 1988. Stock Aitken and Waterman wrote and produced the track which was the lead-off single and lead track from Rick’s debut LP “Whenever You Need Somebody”. The album was itself a UK number one and would go on to sell over 15 million copies worldwide.\n\nThe legendary video was directed by Simon West – who later went on to make Hollywood blockbusters such as Con Air, Lara Croft – Tomb Raider and The Expendables 2. The video passed the 1bn YouTube views milestone on 28 July 2021.\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/YTSubID\n\nFollow Rick Astley:\nFacebook: https://RickAstley.lnk.to/FBFollowID \nTwitter: https://RickAstley.lnk.to/TwitterID \nInstagram: https://RickAstley.lnk.to/InstagramID \nWebsite: https://RickAstley.lnk.to/storeID \nTikTok: https://RickAstley.lnk.to/TikTokID\n\nListen to Rick Astley:\nSpotify: https://RickAstley.lnk.to/SpotifyID \nApple Music: https://RickAstley.lnk.to/AppleMusicID \nAmazon Music: https://RickAstley.lnk.to/AmazonMusicID \nDeezer: https://RickAstley.lnk.to/DeezerID \n\nLyrics:\nWe’re no strangers to love\nYou know the rules and so do I\nA full commitment’s what I’m thinking of\nYou wouldn’t get this from any other guy\n\nI just wanna tell you how I’m feeling\nGotta make you understand\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\nWe’ve known each other for so long\nYour heart’s been aching but you’re too shy to say it\nInside we both know what’s been going on\nWe know the game and we’re gonna play it\n\nAnd if you ask me how I’m feeling\nDon’t tell me you’re too blind to see\n\nNever gonna give you up\nNever gonna let you down\nNever gonna run around and desert you\nNever gonna make you cry\nNever gonna say goodbye\nNever gonna tell a lie and hurt you\n\n#RickAstley #NeverGonnaGiveYouUp #WheneverYouNeedSomebody #OfficialMusicVideo", "default_language": "en" }, "flags": { "deleted": false, "nsfw": null, "spoiler": null, "pinned": null } }, "computed": { "engagement_rate": 0.012107, "language": "en", "content_category": "entertainment", "estimated_reach": 2146878767 } }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } }, "/telegram/search": { "get": { "summary": "Search Telegram channels by keyword", "description": "Finds public Telegram channels by keyword, so you can pick the channels to read with `/v1/telegram/profile` and `/v1/telegram/profile/posts`. Channels are discovered through a public web search index limited to t.me pages, so this finds what that index has already seen: it is not real time, a channel or message from the last few days may not appear yet, and private channels and invite-only groups never appear. Returns one row per channel, in the order the search found them, on the same Author shape `/v1/telegram/profile` returns: `author.username` is the public handle (pass it as `handle`), `author.url` is `https://t.me/`, and `author.display_name` is the channel's title when the search result carried it (null when the result showed only the handle). `author.ext.search_hit` says how the channel was found: `match` is `channel_page` (the channel's own page) or `post_in_channel` (a message or the message preview), `title` and `snippet` are the hit as the index showed it, `evidence_url` is the first page that matched, and `matched_urls` lists every t.me page the search matched for that channel, so you can open the exact messages. The snippet is the index's text, not the channel's description, so `author.bio` stays null on a plain call, as do `author.followers`, `author.avatar_url` and `author.verified`. Send `include=details` and every channel is joined, in the same call, to the profile lookup: the exact subscriber count (`author.followers`), the description (`author.bio`), the avatar, the verified flag and, where it was null, the title land on each row. Words in `query` match loosely; put a phrase in double quotes to require it, and add `-word` to exclude a word. Cost: 2 credits for the page, plus 1 credit per channel filled from a fresh lookup with `include=details` (at most 10 a page, so 12 credits at most); channels already in cache are free, channels that could not be filled are refunded, and a search that finds no public channel is a 404 at 0 credits. Time: a plain page takes about 2 to 12 seconds; `include=details` adds a few seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 10 seconds) and nothing when the channels are already cached. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. A page holds up to 10 channels, fewer when several hits belong to one channel. Forward `pagination.next_cursor` as `cursor` for the next page; the same channel can appear again on a later page. Keyword hits include coupon and reseller channels that merely contain your words: send `relevance=filter` to drop the channels that are not about your query, or add `relevant_to=` with a sentence describing the channels you want (for example `shops selling cheap or replica watches`) to judge them against that instead; each channel is judged on its title and the search snippet.", "tags": [ "telegram" ], "operationId": "get_telegram_search", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-credit-tier": "standard", "x-credit-cost": 2, "x-credit-cost-min": 2, "x-credit-cost-max": 16, "x-credit-cost-formula": "2 credits for the page. include=details holds 1 credit per channel (at most 10 a page, fewer with limit) and keeps only the channels filled from a fresh lookup, so a page is at most 12 credits; channels served from cache are free, unfilled channels are refunded, and a search that finds no public channel costs 0. Relevance against your query (by default, or with relevance=) is free. Adding relevant_to= holds 4 extra credits and refunds down to 1 credit per started 25 rows that were newly judged: rows already judged for the same topic are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Keywords describing the channels or messages to find, for example `byd spare parts`. Put a phrase in double quotes to require it. Keywords only: the search is already limited to public Telegram pages, so a `site:` operator is refused before billing.", "schema": { "type": "string" }, "example": "byd spare parts" }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1. Forwarding `pagination.next_cursor` as `cursor` does the same. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.", "deprecated": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "date_posted", "in": "query", "required": false, "description": "Only pages the search index dates within this window: last-hour, last-day, last-week, last-month or last-year. Useful for monitoring new activity.", "schema": { "type": "string", "enum": [ "last-hour", "last-day", "last-week", "last-month", "last-year" ] } }, { "name": "region", "in": "query", "required": false, "description": "Two-letter country code (US, AE, IN, KR) whose results to prefer.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Return at most this many channels from the page (1 to 10). With `include=details` it also lowers the credits held, one per channel.", "schema": { "type": "integer", "minimum": 1, "maximum": 10 } }, { "name": "include", "in": "query", "required": false, "description": "Set to `details` (one token only) to fill, on every channel in this one call, `author.followers` (the exact subscriber count), `author.bio` (the description), `author.avatar_url`, `author.verified`, and the title where it was null. Holds 1 credit per channel (at most 10 a page) and keeps only the channels filled from a fresh lookup; channels already in cache and channels the lookup cannot fill are refunded, so a page is never more than 12 credits. Read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged.", "schema": { "type": "string", "enum": [ "details" ] } }, { "name": "relevance", "in": "query", "required": false, "description": "Optional. Without this param every row already carries computed.relevance against your query, free ({ p, sense, depth, spam }: is this row about what your query means, or a different thing that shares its words?), and nothing is dropped or reordered. score asks for it explicitly and waits for every row; filter also drops the rows that are not about your query, and lists their ids in data.relevance.dropped_ids. Your query is the topic; nothing to configure. A row that could not be judged is never dropped and carries relevance: null. Pagination is unchanged, so a filtered page can hold fewer rows. Free with your query as the topic; with relevant_to it adds 1 credit per started 25 newly judged rows (rows already judged for the same topic are free, and so is a cached page).", "schema": { "type": "string", "enum": [ "score", "filter" ] } }, { "name": "relevance_threshold", "in": "query", "required": false, "description": "Optional, only with relevance. The probability (0 to 1) a row must reach to be kept by relevance=filter. Default 0.5. Lower keeps more rows, higher keeps fewer.", "schema": { "type": "string" } }, { "name": "relevant_to", "in": "query", "required": false, "description": "Optional, only with relevance. Up to 200 characters describing what you mean, used as the topic instead of the query. Use it when the query is ambiguous, for example query=cleopatra with relevant_to=Cleopatra, the IGT slot game.", "schema": { "type": "string" } }, { "name": "judgments", "in": "query", "required": false, "description": "Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same.", "schema": { "type": "string", "enum": [ "on", "off" ] } }, { "name": "dry_run", "in": "query", "required": false, "description": "Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "fit", "in": "query", "required": false, "description": "Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged.", "schema": { "type": "string", "enum": [ "goal" ] } }, { "name": "goal", "in": "query", "required": false, "description": "Required by fit=goal. What you are trying to do, in your own words, up to 300 characters.", "schema": { "type": "string" } }, { "name": "fit_tokens", "in": "query", "required": false, "description": "Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it.", "schema": { "type": "integer" } }, { "name": "max_pages", "in": "query", "required": false, "description": "1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "max_items", "in": "query", "required": false, "description": "1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: \"max_items\"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`\"time_budget\"`): send the returned cursor with the same params to continue.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "max_credits", "in": "query", "required": false, "description": "1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: \"max_credits\"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "cursor", "in": "query", "required": false, "description": "Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint's native `page` (page style). You never construct, decode, or look up a cursor. Omit it for page 1.", "schema": { "type": "string" } }, { "name": "max_age_s", "in": "query", "required": false, "description": "The oldest cached copy you accept, in seconds. A copy that old or younger is served for 0 credits, with its age in `age_s` and the `X-Cache-Age` header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like `Cache-Control: no-cache`.", "schema": { "type": "integer", "minimum": 0, "maximum": 120 } }, { "name": "Cache-Control", "in": "header", "required": false, "description": "Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. To accept an older cached copy, or to require a younger one, send the `max_age_s` query parameter instead. See the Response Schema guide for details.", "schema": { "type": "string" }, "example": "no-cache" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives `409 IDEMPOTENCY_IN_PROGRESS` with a `Retry-After` of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use `Accept: application/json` when sending this header. The unsupported key-plus-SSE combination is rejected before billing.", "schema": { "type": "string" }, "example": "7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c" }, { "name": "Prefer", "in": "header", "required": false, "description": "Send `respond-async` to run this GET in the background instead of waiting on the socket (or add `?async=true` to the query). The answer is 202 with `data.job_id`, a `Location` header and `Retry-After`; read the result free at `GET /v1/prism/jobs/{job_id}`, where `results[0].response` is exactly what this call returns. Nothing is held at submit: the call is validated now and billed as this call when it runs. Use it for calls that can outlast your client's timeout (MCP and many HTTP clients stop at 30 s). `Idempotency-Key` returns the same job on a retry.", "schema": { "type": "string" }, "example": "respond-async" } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Credits-Used": { "description": "Net credits charged for this response. Idempotency replays report 0.", "schema": { "type": "integer", "minimum": 0 } }, "X-Credits-Remaining": { "description": "Current authoritative balance. Free cache hits and idempotency replays omit this header when the balance cannot be determined; body `credits_remaining` is null instead.", "schema": { "type": "integer", "minimum": 0 } }, "X-Key-Credits-Remaining": { "description": "Only when the API key has a credit limit: the credits this key may still spend under that limit, after this call (never below 0). Absent for a key with no limit. `GET /v1/keys/current` has the limit and what is used.", "schema": { "type": "integer", "minimum": 0 } }, "X-Idempotent-Replay": { "description": "Present with value `true` only when this response replays a settled idempotency record.", "schema": { "type": "string", "enum": [ "true" ] } }, "Idempotent-Replayed": { "description": "Present with value `true` only when this response replays a settled idempotency record. Same meaning as `X-Idempotent-Replay`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded", "example": true }, "platform": { "type": "string", "description": "Platform name", "example": "telegram" }, "endpoint": { "type": "string", "description": "API endpoint path", "example": "/v1/telegram/search" }, "data": { "type": "object", "description": "Platform-specific response data", "properties": { "items": { "type": "array", "description": "Array of canonical author wrappers ({ author })", "items": { "type": "object", "description": "Canonical author wrapper", "properties": { "author": { "type": "object", "description": "Canonical Author object (unified across all platforms)", "properties": { "id": { "type": "string", "description": "Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)" }, "username": { "type": [ "string", "null" ], "description": "User handle or username" }, "display_name": { "type": [ "string", "null" ], "description": "Display name or full name" }, "avatar_url": { "type": [ "string", "null" ], "description": "URL to profile picture" }, "bio": { "type": [ "string", "null" ], "description": "Profile biography or description" }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified" }, "followers": { "type": [ "number", "null" ], "description": "Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true." }, "following": { "type": [ "number", "null" ], "description": "Number of accounts followed" }, "posts_count": { "type": [ "number", "null" ], "description": "Total number of posts / videos / tracks / episodes" }, "likes_count": { "type": [ "number", "null" ], "description": "Total likes received across the author's content (when surfaced)" }, "url": { "type": [ "string", "null" ], "description": "Direct URL to the profile page" }, "location": { "type": [ "string", "null" ], "description": "ISO region code (e.g. `US`) or freeform location string when surfaced" }, "external_url": { "type": [ "string", "null" ], "description": "Bio link / external website URL when surfaced by the platform" }, "private": { "type": [ "boolean", "null" ], "description": "Boolean at author.private" }, "joined_at": { "type": [ "string", "null" ], "description": "String at author.joined_at" }, "last_post_at": { "type": [ "string", "null" ], "description": "String at author.last_post_at" }, "ext": { "type": [ "object", "null" ], "description": "Nested object: author.ext", "properties": { "social_context": { "type": [ "string", "null" ], "description": "String at author.ext.social_context" }, "account_created": { "type": [ "string", "null" ], "description": "String at author.ext.account_created" }, "country": { "type": [ "string", "null" ], "description": "String at author.ext.country" }, "country_name": { "type": [ "string", "null" ], "description": "String at author.ext.country_name" }, "collects_received": { "type": [ "number", "null" ], "description": "Numeric at author.ext.collects_received" }, "former_usernames": { "type": [ "array", "null" ], "description": "Array at author.ext.former_usernames", "items": { "type": "string", "description": "String at author.ext.former_usernames" } }, "former_usernames_count": { "type": [ "integer", "null" ], "description": "Instagram profile/about: how many former usernames Instagram's \"About this account\" panel lists for the account. 0 when the panel lists none, null when the panel could not be read on this call (the response then carries a note saying so). A count above 0 means the handle was renamed at least once; the names themselves are not published." }, "verified_at": { "type": [ "string", "null" ], "description": "Instagram profile/about, opt-in (`include=verified_at`): the month Instagram verified the account, as the panel shows it (\"April 2024\"). A month, not a date. Null when the account is not verified or the panel shows no verification date. Absent unless requested." }, "public_email": { "type": [ "string", "null" ], "description": "String at author.ext.public_email" }, "contact_email": { "type": [ "string", "null" ], "description": "Opt-in (`contact_email=1` on instagram/profile, youtube/channel and youtube/channel/about). When the bio lists two or more email addresses, the one the creator gives for contacting them personally, copied verbatim. Null when there is one address or none, when every address belongs to a manager, agency or brand, or when the choice was not confident. `author.ext.public_email` (the first address in the bio) is unchanged." }, "public_phone": { "type": [ "string", "null" ], "description": "String at author.ext.public_phone" }, "similar_source": { "type": [ "string", "null" ], "description": "String at author.ext.similar_source" }, "instagram_username": { "type": [ "string", "null" ], "description": "String at author.ext.instagram_username" }, "similar_via": { "type": [ "string", "null" ], "description": "String at author.ext.similar_via" }, "business_category": { "type": [ "string", "null" ], "description": "String at author.ext.business_category" }, "bio_links": { "type": [ "array", "null" ], "description": "Array at author.ext.bio_links", "items": { "type": "object", "description": "Nested object: author.ext.bio_links", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.title" }, "url": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.url" }, "link_type": { "type": [ "string", "null" ], "description": "String at author.ext.bio_links.link_type" } } } }, "is_business": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_business" }, "is_professional": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_professional" }, "creator_marketplace": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.creator_marketplace" }, "verification_label": { "type": [ "string", "null" ], "description": "String at author.ext.verification_label" }, "fbid": { "type": [ "string", "null" ], "description": "String at author.ext.fbid" }, "hd_avatar_url": { "type": [ "string", "null" ], "description": "String at author.ext.hd_avatar_url" }, "website": { "type": [ "string", "null" ], "description": "String at author.ext.website" }, "cover_url": { "type": [ "string", "null" ], "description": "String at author.ext.cover_url" }, "page_active": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.page_active" }, "employee_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count" }, "employee_count_range": { "type": [ "object", "null" ], "description": "Nested object: author.ext.employee_count_range", "properties": { "start": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.start" }, "end": { "type": [ "number", "null" ], "description": "Numeric at author.ext.employee_count_range.end" } } }, "founded_year": { "type": [ "number", "null" ], "description": "Numeric at author.ext.founded_year" }, "company_type": { "type": [ "string", "null" ], "description": "String at author.ext.company_type" }, "tagline": { "type": [ "string", "null" ], "description": "String at author.ext.tagline" }, "specialities": { "type": [ "array", "null" ], "description": "Array at author.ext.specialities", "items": { "type": "string", "description": "String at author.ext.specialities" } }, "industries": { "type": [ "array", "null" ], "description": "Array at author.ext.industries", "items": { "type": "string", "description": "String at author.ext.industries" } }, "headquarters": { "type": [ "object", "null" ], "description": "Object at author.ext.headquarters" }, "locations": { "type": [ "array", "null" ], "description": "Array at author.ext.locations", "items": { "description": "Leaf at author.ext.locations" } }, "hashtags": { "type": [ "array", "null" ], "description": "Array at author.ext.hashtags", "items": { "description": "Leaf at author.ext.hashtags" } }, "funding": { "type": [ "object", "null" ], "description": "Object at author.ext.funding" }, "address": { "type": [ "string", "null" ], "description": "String at author.ext.address" }, "price_range": { "type": [ "string", "null" ], "description": "String at author.ext.price_range" }, "rating": { "type": [ "string", "null" ], "description": "String at author.ext.rating" }, "rating_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.rating_count" }, "talking_about_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.talking_about_count" }, "business_hours": { "type": [ "array", "null" ], "description": "Array at author.ext.business_hours", "items": { "description": "Leaf at author.ext.business_hours" } }, "links": { "type": [ "array", "null" ], "description": "Array at author.ext.links", "items": { "description": "Leaf at author.ext.links" } }, "ad_library_page_id": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_page_id" }, "ad_library_status": { "type": [ "string", "null" ], "description": "String at author.ext.ad_library_status" }, "urn": { "type": [ "string", "null" ], "description": "String at author.ext.urn" }, "is_top_voice": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_top_voice" }, "is_premium": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_premium" }, "is_creator": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_creator" }, "is_influencer": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_influencer" }, "is_open_to_work": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_open_to_work" }, "is_hiring": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_hiring" }, "member_id": { "type": [ "string", "null" ], "description": "String at author.ext.member_id" }, "company_id": { "type": [ "string", "null" ], "description": "String at author.ext.company_id" }, "reaction_type": { "type": [ "string", "null" ], "description": "String at author.ext.reaction_type" }, "followers_approximate": { "type": [ "boolean", "null" ], "description": "True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts." }, "counts_source": { "type": [ "string", "null" ], "enum": [ "app", "web", null ], "description": "TikTok profile only. Which of TikTok's two live counter sets `author.followers`, `author.following`, `author.likes_count` and `author.posts_count` carry: `app` (TikTok's app counters, the default) or `web` (the website's `statsV2`, returned with `counts=web`). The two sets can differ by a few percent in either direction." }, "keywords": { "type": [ "string", "null" ], "description": "String at author.ext.keywords" }, "total_views": { "type": [ "number", "null" ], "description": "Numeric at author.ext.total_views" }, "joined_at_timestamp": { "type": [ "string", "null" ], "description": "String at author.ext.joined_at_timestamp" }, "topicCategories": { "type": [ "array", "null" ], "description": "Array at author.ext.topicCategories", "items": { "type": "string", "description": "String at author.ext.topicCategories" } }, "bannerExternalUrl": { "type": [ "string", "null" ], "description": "String at author.ext.bannerExternalUrl" }, "madeForKids": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.madeForKids" }, "hiddenSubscriberCount": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.hiddenSubscriberCount" }, "related_playlists": { "type": [ "object", "null" ], "description": "Object at author.ext.related_playlists" }, "topic_ids": { "type": [ "array", "null" ], "description": "Array at author.ext.topic_ids", "items": { "type": "string", "description": "String at author.ext.topic_ids" } }, "unsubscribed_trailer": { "type": [ "string", "null" ], "description": "String at author.ext.unsubscribed_trailer" }, "localizations": { "type": [ "object", "null" ], "description": "Object at author.ext.localizations", "additionalProperties": { "type": "object", "description": "Nested object: author.ext.localizations.*", "properties": { "title": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.title" }, "description": { "type": [ "string", "null" ], "description": "String at author.ext.localizations.*.description" } } } }, "monthly_listeners": { "type": [ "number", "null" ], "description": "Numeric at author.ext.monthly_listeners" }, "total_ratings": { "type": [ "number", "null" ], "description": "Spotify podcasts only: how many listeners have rated the show. Cumulative over the show's whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)" }, "average_rating": { "type": [ "number", "null" ], "description": "Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf" }, "creator_username": { "type": [ "string", "null" ], "description": "String at author.ext.creator_username" }, "join_policy": { "type": [ "string", "null" ], "description": "String at author.ext.join_policy" }, "is_nsfw": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.is_nsfw" }, "rules": { "type": [ "array", "null" ], "description": "Array at author.ext.rules", "items": { "type": "object", "description": "Object at author.ext.rules" } }, "weekly_active_users": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_active_users" }, "weekly_contributions": { "type": [ "number", "null" ], "description": "Numeric at author.ext.weekly_contributions" }, "rules_text": { "type": [ "string", "null" ], "description": "String at author.ext.rules_text" }, "language": { "type": [ "string", "null" ], "description": "String at author.ext.language" }, "post_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.post_karma" }, "comment_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.comment_karma" }, "awardee_karma": { "type": [ "number", "null" ], "description": "Numeric at author.ext.awardee_karma" }, "trophy_count": { "type": [ "number", "null" ], "description": "Numeric at author.ext.trophy_count" }, "banner_url": { "type": [ "string", "null" ], "description": "String at author.ext.banner_url" }, "profile_title": { "type": [ "string", "null" ], "description": "String at author.ext.profile_title" }, "social_links": { "type": [ "array", "null" ], "description": "Array at author.ext.social_links", "items": { "description": "Leaf at author.ext.social_links" } }, "bio_link": { "type": [ "string", "null" ], "description": "String at author.ext.bio_link" }, "embed_html": { "type": [ "string", "null" ], "description": "String at author.ext.embed_html" }, "embed_url": { "type": [ "string", "null" ], "description": "String at author.ext.embed_url" }, "group": { "type": [ "object", "null" ], "description": "Object at author.ext.group" }, "search_hit": { "type": [ "object", "null" ], "description": "Nested object: author.ext.search_hit", "properties": { "match": { "type": [ "string", "null" ], "enum": [ "group_page", "post_in_group", "channel_page", "post_in_channel", null ], "description": "Leaf at author.ext.search_hit.match" }, "title": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.title" }, "snippet": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.snippet" }, "evidence_url": { "type": [ "string", "null" ], "description": "String at author.ext.search_hit.evidence_url" }, "matched_urls": { "type": [ "array", "null" ], "description": "Array at author.ext.search_hit.matched_urls", "items": { "type": "string", "description": "String at author.ext.search_hit.matched_urls" } } } }, "blog_name": { "type": [ "string", "null" ], "description": "String at author.ext.blog_name" }, "blog_no": { "type": [ "string", "null" ], "description": "String at author.ext.blog_no" }, "visitors_today": { "type": [ "number", "null" ], "description": "Numeric at author.ext.visitors_today" }, "visitors_total": { "type": [ "number", "null" ], "description": "Numeric at author.ext.visitors_total" }, "topic": { "type": [ "string", "null" ], "description": "String at author.ext.topic" }, "power_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.power_blog" }, "official_blog": { "type": [ "boolean", "null" ], "description": "Boolean at author.ext.official_blog" } } } } } } } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results." }, "total": { "type": [ "integer", "null" ], "description": "Total number of matching results, when the upstream provides a count. Omitted otherwise." }, "relevance": { "type": "object", "description": "Present on a list that scores its rows against your query: free by default, or when you send `relevance=score` or `relevance=filter`. Absent with `judgments=off`. Reports what was scored, what a `filter` dropped and what it cost.", "properties": { "mode": { "type": "string", "enum": [ "score", "filter" ], "description": "`score`: rows carry `computed.relevance` and none is dropped. `filter`: rows judged off topic are also dropped.", "example": "score" }, "topic_source": { "type": "string", "enum": [ "query", "relevant_to" ], "description": "Where the topic came from: your search query, or the `relevant_to` you sent.", "example": "query" }, "origin": { "type": "string", "enum": [ "default", "requested" ], "description": "`default` when you sent no `relevance=` (score only, free, never drops or reorders), `requested` when you asked.", "example": "default" }, "rows": { "type": "integer", "description": "Rows on the page before any drop.", "example": 30 }, "scored": { "type": "integer", "description": "Rows that carry a relevance value, freshly judged or from the shared store.", "example": 30 }, "cached": { "type": "integer", "description": "Of `scored`, rows served from the shared store.", "example": 0 }, "kept": { "type": "integer", "description": "Rows left on the page.", "example": 30 }, "dropped": { "type": "integer", "description": "Rows removed by `relevance=filter`.", "example": 0 }, "dropped_ids": { "type": "array", "description": "Ids of the rows counted in `dropped`.", "items": { "type": "string", "description": "A row id." } }, "unjudged": { "type": "integer", "description": "Rows the judgment could not answer for this time. They are kept and carry `relevance: null`.", "example": 0 }, "too_short": { "type": "integer", "description": "Rows with too little text to judge. They are kept.", "example": 0 }, "threshold": { "type": "number", "description": "The probability a row needs to be kept by `relevance=filter`: 0.5, or the `relevance_threshold` you sent.", "example": 0.5 }, "extra_credits": { "type": "integer", "description": "Credits the judgment added to this call. 0 with your query as the topic.", "example": 0 }, "methodology_version": { "type": "string", "description": "The version of the relevance questions.", "example": "relevance/2" }, "status": { "type": "string", "enum": [ "complete", "partial", "skipped" ], "description": "`complete`: every row was scored. `partial`: some rows carry `relevance: null`. `skipped`: default scoring was switched off by a capacity guard.", "example": "complete" }, "pending": { "type": "integer", "description": "Rows still being judged when the page was sent.", "example": 0 }, "pending_ids": { "type": "array", "description": "Ids of the rows counted in `pending`.", "items": { "type": "string", "description": "A row id." } }, "cached_page": { "type": "boolean", "description": "Present and true when the whole page came from the response cache, so nothing was judged or charged." }, "unjudged_dropped": { "type": "object", "description": "Present on a merged multi-platform search under `relevance=filter`: rows dropped because they could not be judged in time, counted per platform." }, "context_hash": { "type": "string", "description": "Present on a leg of a merged multi-platform search: a hash of the topic judged." }, "fresh_ids": { "type": "array", "description": "Present on a leg of a merged multi-platform search: the rows judged afresh on this leg.", "items": { "type": "string", "description": "A row id." } } } }, "walk": { "type": "object", "description": "Present when the request sent a row-walk param (`max_pages` above 1, `max_items`, `max_credits`, a row filter, `sort_rows` or `seen`). What the walk did across the pages it fetched. Each page is billed as one call, and its charge is recorded under its own request id.", "properties": { "pages": { "type": "integer", "description": "Pages fetched.", "example": 3 }, "stopped": { "type": "string", "enum": [ "end", "max_pages", "max_items", "max_credits", "time_budget", "page_error" ], "description": "Why the walk stopped. `end`: the list ran out. `max_pages`, `max_items` or `max_credits`: the limit you set was reached. `time_budget`: the request's time budget ran low. `page_error`: a later page failed. Unless it is `end`, `pagination.next_cursor` continues from where the walk stopped.", "example": "max_pages" }, "rows_fetched": { "type": "integer", "description": "Rows read across every page, before any filter.", "example": 60 }, "rows_returned": { "type": "integer", "description": "Rows in `data.items`.", "example": 41 }, "discarded": { "type": "object", "description": "Present when you sent a row filter. Rows the filters removed, counted once each under the first filter they failed. A row a filter cannot verify (no view count, no date, no country) is discarded.", "properties": { "views_below_min": { "type": "integer", "description": "Rows with fewer views than `min_views`." }, "views_unknown": { "type": "integer", "description": "Rows with no view count, when `min_views` was sent." }, "older_than_max_age": { "type": "integer", "description": "Rows published before the `max_age_days` window." }, "date_unknown": { "type": "integer", "description": "Rows with no publish date, when `max_age_days` was sent." }, "country_not_included": { "type": "integer", "description": "Rows registered to a country that is not in `country`." }, "country_unknown": { "type": "integer", "description": "Rows with no country, when `country` was sent." }, "country_excluded": { "type": "integer", "description": "Rows registered to a country listed in `exclude_country`." } } }, "repeats": { "type": "integer", "description": "Present when you sent `seen`: rows removed because your account already received them under that id." }, "duplicates": { "type": "integer", "description": "Present when above zero: rows a later page repeated from an earlier page of the same walk, kept once." }, "credits": { "type": "object", "description": "What the pages cost.", "properties": { "pages": { "type": "integer", "description": "Credits charged for the pages walked, before refunds." }, "refunded": { "type": "integer", "description": "Credits refunded across the pages." } } }, "request_ids": { "type": "array", "description": "The request id of each page walked. Each is its own entry in `GET /v1/credits/transactions`.", "items": { "type": "string", "description": "A row id." } } } }, "hydration": { "type": "object", "description": "Present when the request asked for a row join with `include=`, or sent a param that implies one. What the join did and what it cost. On a multi-page walk it sums every page. A join that always runs for free is left out.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." }, "steps": { "type": "array", "description": "Present when the request asked for more than one join (`include=engagement,channel`): one report per join, in the order they ran. The top-level numbers are then the page's: rows looked up or filled by any join, and the credits and time of all of them together.", "items": { "type": "object", "description": "One join's report.", "properties": { "include": { "type": "string", "description": "The token that switched the join on.", "example": "profile" }, "implied_by": { "type": "string", "description": "Present when you did not send `include` and another param switched the join on. The join's credits (`extra_credits`) are then part of `credits_used`. Absent when you sent `include` yourself." }, "rows": { "type": "integer", "description": "Rows on the page after any row cap.", "example": 20 }, "looked_up": { "type": "integer", "description": "Rows that needed a lookup (at least one field the join fills was empty).", "example": 20 }, "filled": { "type": "integer", "description": "Rows where at least one field was filled by the join.", "example": 18 }, "cached": { "type": "integer", "description": "Of `filled`, rows filled from the sibling endpoint's cache at no charge.", "example": 0 }, "unfilled": { "type": "integer", "description": "Rows that needed a lookup and were not filled (the lookup failed, was skipped, or had nothing to copy). Their credits are refunded.", "example": 2 }, "credits_held": { "type": "integer", "description": "Credits held up front for the join, on top of the page's own price.", "example": 20 }, "extra_credits": { "type": "integer", "description": "Of `credits_held`, the credits kept: one lookup's price for each distinct key filled from a fresh lookup. The rest was refunded.", "example": 18 }, "ms": { "type": "integer", "description": "Time the join added, in milliseconds.", "example": 2400 }, "cached_page": { "type": "boolean", "description": "True when the whole page was served from cache, so the join cost nothing on this call.", "example": true }, "batches": { "type": "integer", "description": "Joins that look rows up in batches only: how many batch calls were made. Absent on a join that looks rows up one by one." }, "from_earlier_pages": { "type": "integer", "description": "`max_pages`, `max_items` and `max_credits` walks only: rows filled free from a key already looked up on an earlier page of the same walk. Not counted in `looked_up`, `filled` or `cached`. Absent when zero." } } } } } }, "estimate": { "type": "object", "description": "Present only on a dry run (`dry_run=1`). A dry run charges 0 credits, fetches nothing and returns `data.valid`, `data.normalized_params` and this `estimate` in place of the usual rows. An invalid request is the normal free 400 instead.", "properties": { "kind": { "type": "string", "description": "Always `estimate`.", "example": "estimate" }, "version": { "type": "integer", "description": "The version of this estimate shape.", "example": 1 }, "id": { "type": "string", "description": "The endpoint, as `platform/resource`." }, "method": { "type": "string", "description": "The HTTP method.", "example": "GET" }, "valid": { "type": "boolean", "description": "True when the request would pass every check made before billing.", "example": true }, "hold": { "type": "integer", "description": "Exactly what the router would deduct up front for this request." }, "expected_min": { "type": "integer", "description": "The least a successful call settles at." }, "expected_max": { "type": "integer", "description": "The most a call can settle at. Unused hold is refunded." }, "unit": { "type": "string", "description": "Always `credits`.", "example": "credits" }, "pricing": { "type": "string", "enum": [ "flat", "metered" ], "description": "`flat`: the same price every call. `metered`: the price depends on the work done, and unused hold is refunded.", "example": "flat" }, "formula": { "type": "string", "description": "How the price is worked out, in words." }, "levers": { "type": "array", "description": "Params that change the price, each with the hold for the same request with that one change.", "items": { "type": "object", "description": "One lever.", "properties": { "param": { "type": "string", "description": "The param to change." }, "hold": { "type": "integer", "description": "The hold for the same request with this one change." }, "effect": { "type": "string", "description": "What the change does." } } } }, "cached_likely": { "type": "boolean", "description": "Always false: a dry run does not read the cache.", "example": false }, "normalized_params": { "type": "object", "description": "The params the router prices, after its own normalisation." }, "notes": { "type": "array", "description": "Plain-English notes about this quote.", "items": { "type": "string", "description": "One note." } }, "warnings": { "type": "array", "description": "Notices about the quote, such as a page count that had to be assumed.", "items": { "type": "string", "description": "One notice." } }, "rows_expected": { "type": "integer", "description": "Judged lists only: the most rows one call judges on this endpoint." }, "rows_cached": { "type": "integer", "description": "Judged lists only: rows already judged and free. 0 on a dry run, which sees no rows." }, "label_credits_min": { "type": "integer", "description": "Judged lists only: the least the paid labels add. 0 on a dry run, which sees no rows." }, "label_credits_max": { "type": "integer", "description": "Judged lists only: the most the paid labels can add. 0 when you asked for no paid label." }, "base_credits": { "type": "integer", "description": "Judged lists only: the call's price without the label and relevance holds." } } }, "held_back": { "type": "object", "description": "Present when you sent `fit=goal` with a `goal` and at least one block of the page was not needed for it. The held rows (or fields) stay in place as stubs of `{ id, held: true }`; this block lists them.", "properties": { "ids": { "type": "array", "description": "Ids of the rows or fields that were held back.", "items": { "type": "string", "description": "A row id." } }, "recall": { "type": "string", "description": "A recall id for the full page, which re-reads it from cache at no extra charge.", "example": "fit_3f9a1c0b7d2e4a58" } } }, "dropped": { "type": "integer", "description": "Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.", "example": 0 }, "empty_reason": { "type": "string", "enum": [ "no_matches", "end_of_list", "nothing_new_since", "window_filtered", "relevance_filtered", "row_filtered", "already_seen", "source_empty_unverified" ], "description": "Present only when `items` is empty: why this page has no rows. Read it with `pagination.has_more`, which still says whether to keep paging. `no_matches`: The source answered and has no rows for this request. The same call returns the same answer, so change the query or the filters to get rows. `end_of_list`: This page was requested with a cursor and the list has no more rows. Stop paging. `nothing_new_since`: The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary. `window_filtered`: Every row on this page fell outside your date window (since, until, recent_days) or was a pinned post you excluded. Keep paging while pagination.has_more is true, or widen the window. `relevance_filtered`: relevance=filter judged every row on this page off-topic, and their ids are in data.relevance.dropped_ids. Keep paging while pagination.has_more is true, or send relevance=score to keep every row. `row_filtered`: A row filter you sent (such as country or min_views) kept no row on this page, and the report beside items counts what it dropped. Keep paging while pagination.has_more is true, or loosen the filter. `already_seen`: Every row on this page was one already returned to you on this walk, so there is nothing new here. Keep paging while pagination.has_more is true. `source_empty_unverified`: The source returned no rows and nothing confirmed it: no second source agreed, a source failed on the way, or a page mid-list came back empty. Retry later or with Cache-Control: no-cache, and keep paging while pagination.has_more is true.", "example": "nothing_new_since" }, "empty_reason_note": { "type": "string", "description": "Present only beside `empty_reason`: one or two sentences for a person or an agent saying what the code means and what to do next. The wording can improve; branch on `empty_reason`.", "example": "The walk reached your since or stop_at_id boundary before any newer row, so nothing was published after it. Poll again later with the same boundary." }, "_warnings": { "type": "array", "description": "Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.", "items": { "type": "string", "description": "One advisory notice." } } }, "required": [ "dropped" ] }, "credits_used": { "type": "integer", "description": "Number of credits consumed", "example": 1 }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.", "example": 4999 }, "credits_remaining_note": { "type": "string", "description": "Present only when `credits_remaining` is null by design, as on a free cache hit: says why the balance was not read and where to read it.", "example": "not read on cache hits (credits_used is 0); call GET /v1/credits/balance for the current balance" }, "request_id": { "type": "string", "description": "Unique request identifier for support", "example": "req-abc123" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache", "example": false }, "age_s": { "type": [ "integer", "null" ], "description": "Present only on a cache hit (`cached: true`): whole seconds since this copy was fetched, also sent as the `X-Cache-Age` header. Null for a copy stored before ages were recorded. Send `max_age_s` to set how old a copy you accept: a profile or post copy up to an hour old is served for 0 credits, and a lower value fetches fresh.", "example": 340 }, "idempotent_replay": { "type": "boolean", "description": "True only when this response is an idempotency replay", "example": true }, "meta": { "type": "object", "description": "Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.", "properties": { "hint": { "type": "object", "description": "One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.", "properties": { "code": { "type": "string", "description": "creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat | batch_comments | batch_jobs", "example": "search_multi" }, "message": { "type": "string", "description": "One sentence for a person or an agent to read.", "example": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged." }, "method": { "type": "string", "description": "GET or POST.", "example": "GET" }, "path": { "type": "string", "description": "The call the hint points to.", "example": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube" } } } } }, "pagination": { "type": "object", "description": "Cursor state for this page. Present on every list response.", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.", "example": "sc.eyJ2IjoyLCJjIjoiMiIsInAiOiJwYWdlIn0" }, "has_more": { "type": "boolean", "description": "Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.", "example": true }, "page_size": { "type": "integer", "description": "Number of items in THIS page.", "example": 30 }, "stopped_at": { "type": [ "string", "null" ], "enum": [ "since", "known_id", "end", null ], "description": "Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`).", "example": "known_id" }, "typical_page_size": { "type": [ "integer", "null" ], "description": "How many items a full page of this endpoint usually holds for this request, or null when it has not been verified, as on a source whose page changes with the request's parameters. An endpoint that merges several sources can return more. A page_size below it while has_more is true is a short page from the source, not the end of the list.", "example": 10 }, "next_page_credits": { "type": [ "integer", "null" ], "description": "Credits the next page costs: what sending next_cursor back holds up front, priced from that request by the same pricer that charges it. Flat endpoints charge exactly this; metered endpoints refund what the page does not use; a cached page is free. Null when there is no next page.", "example": 1 } }, "required": [ "next_cursor", "has_more", "page_size" ] } }, "required": [ "success", "platform", "endpoint", "data", "credits_used", "credits_remaining", "request_id", "cached", "pagination" ] }, "example": { "success": true, "platform": "tiktok", "endpoint": "/v1/tiktok/search/users", "data": { "items": [ { "author": { "id": "user_0e9522", "username": "user_759369", "display_name": "user_f0b019", "avatar_url": "https://example.com/avatars/user_0ab01c.png", "bio": null, "verified": null, "followers": 4214875, "following": 1, "posts_count": 2341, "likes_count": 62731828, "url": null, "location": null } }, { "author": { "id": "user_d26411", "username": "user_1f51ed", "display_name": "user_1f51ed", "avatar_url": "https://example.com/avatars/user_a81e65.png", "bio": null, "verified": null, "followers": 1780390, "following": 1, "posts_count": 995, "likes_count": 10060260, "url": null, "location": null } }, { "author": { "id": "user_679d13", "username": "user_c5d687", "display_name": "user_8803ea", "avatar_url": "https://example.com/avatars/user_67de4c.png", "bio": null, "verified": null, "followers": 338243, "following": 374, "posts_count": 464, "likes_count": 2140124, "url": null, "location": null } } ], "next_cursor": "30", "total": 30, "dropped": 0 }, "credits_used": 1, "credits_remaining": 9999, "request_id": "req-8Kq2ZmR4vT9xLb3P", "cached": false, "pagination": { "next_cursor": "sc.eyJ2IjoyLCJjIjoiMzAiLCJwIjoiY3Vyc29yIn0", "has_more": true, "page_size": 30 } } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "402": { "description": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "x-error-codes": [ "INSUFFICIENT_CREDITS", "KEY_BUDGET_EXCEEDED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INSUFFICIENT_CREDITS", "message": "Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit", "status": 402, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "404": { "description": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "x-error-codes": [ "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "RUN_NOT_FOUND", "SCHEDULE_NOT_FOUND", "STREAM_NOT_FOUND" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "ENDPOINT_NOT_FOUND", "message": "Not found - the endpoint does not exist, or the requested resource was not found upstream", "status": 404, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "405": { "description": "Method not allowed - wrong HTTP verb for this endpoint", "x-error-codes": [ "METHOD_NOT_ALLOWED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "METHOD_NOT_ALLOWED", "message": "Method not allowed - wrong HTTP verb for this endpoint", "status": 405, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "409": { "description": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "x-error-codes": [ "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "RUN_STATE_CONFLICT", "STREAM_STATE_CONFLICT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_CONFLICT", "message": "Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation", "status": 409, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "410": { "description": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "x-error-codes": [ "RUN_EXPIRED", "CURSOR_EXPIRED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RUN_EXPIRED", "message": "Gone - the discover run's retention passed and its rows were deleted; start a new run. On the events feed, the cursor is older than the 30-day retention; restart from cursor=oldest", "status": 410, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "422": { "description": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "x-error-codes": [ "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "NEEDS_ASYNC" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "message": "Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)", "status": 422, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "500": { "description": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "x-error-codes": [ "INTERNAL_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INTERNAL_ERROR", "message": "Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit", "status": 500, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "502": { "description": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge", "status": 502, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "503": { "description": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "x-error-codes": [ "SERVICE_UNAVAILABLE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "SERVICE_UNAVAILABLE", "message": "Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge", "status": 503, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "504": { "description": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "x-error-codes": [ "UPSTREAM_ERROR" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "UPSTREAM_ERROR", "message": "Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After", "status": 504, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } } } } }, "x-full-spec": "https://www.socialcrawl.dev/v1/openapi.json" }